Mapping.Value
Mapping.Value is what you put into any mapping field that expects a value:
data, every entry under map, entries in set[], keys under policy, and
anywhere a destination rule field accepts any. It is polymorphic: a value can
be a simple string path, an object with one of several transforming keys, or an
array of those. The shape is defined in
packages/core/src/types/mapping.ts
as Value = ValueType | Array<ValueType>, where ValueType is either a string
(path) or a ValueConfig object.
Options
| Form | Shape | What / When |
|---|---|---|
| Path | string | Reads a dot-path from the event. Use for copying raw fields straight into the output. |
| Constant | { value } | Emits a fixed value. Use when the destination needs a literal like a currency, ID, or label. |
| Map | { map: { key: Value, … } } | Builds an object from multiple paths. Use when the destination expects a structured payload. |
| Loop | { loop: [source, Value] } | Iterates an array source and transforms each item. Use for nested product, cart, or item lists. |
| Set | { set: [Value, Value, …] } | Picks the first defined value from a list. Use as a fallback chain like email then user_id. |
| Fn | { fn: (event, mapping, options) => … } | Runs a custom function on the event. Use only when no declarative form fits. |
| Condition | { condition, value } | Gates the value on a predicate. Use for branching logic inside a single rule. |
| Consent | { consent: {…}, value } | Gates the value on consent states. Use to make individual fields privacy-aware. |
All ValueConfig keys can be combined on the same object: key, condition,
consent, validate act as filters; value, fn, map, loop, set
produce output.
Path
Extract a value by dot-path from the event.
Paths also index into arrays:
Constant
Return a fixed value, independent of the event.
Map
Build an object by mapping keys to their own Mapping.Value.
Loop
Iterate an array source and transform each element. loop: [source, value]:
source selects the array (a path, or 'this' for the event itself), value
transforms each item.
Set
Try each value in order and return the first defined result. Useful as a fallback chain.
{ set: ['data.email', 'user.email', { value: 'anonymous' }] }
Fn
Run a custom function. The handler receives (event, mapping, options) and may
return a promise.
Condition
Only produce output when condition(event) returns truthy.
{
condition: (event) => event.data?.value > 50,
value: 'high_value',
}
Consent
Only produce output when the required consent states are granted on the event.
Validate
validate is a filter, not a form. Combine it with any value-producing key.
The function runs on the produced value; if it returns falsy the result is
dropped (undefined).
Policy
A policy is a record of Mapping.Values applied to the event before the rule
runs. The key is the path the result writes into; the value is any form above.
Config-level policy applies to every event handled by the source or destination:
Event-level policy applies only inside the matched rule:
Processing order: config policy → event matching → event policy → data transformation.
See also
- Mapping.Rule: the rule object that composes values
getMappingValueAPI: programmatic value resolution- Consent guide: consent model in depth