The ID of the mapping definition. The ID is included in the response when you create a mapping definition, or when you retrieve a list of all your mapping definitions.
When locked - updates and deletion of the mapping is not allowed.
Optional lockedEmail of the user who is locking the mapping. If specified, only that user can unlock the mapping.
Scope of the locking, lists all parts of the mapping that are currently locked.
Optional lookupA list of lookup tables that the mapping expressions in this mapping definition can use.
A lookup table is often used to convert a value from one format to another. For example, you can have a list of currencies with a short name, a full name, and a symbol for each currency, like this:
| code | full name | symbol |
|---|---|---|
| USD | U.S. dollar | $ |
| CAD | Canadian dollar | $ |
| EUR | Euro | € |
In a mapping expression, you can use the $lookupTable function to convert a value from one format to the other.
Optional mappingA JSONata document describing the mapping expressions. For example:
\{
"total": item.quantity * item.unit_price,
"currency": item.currency,
"product": product.id
\}
The JSONata document must be converted to a string, so in practice, it doesn't look like the above; it looks like this:
"\{ \"total\": item.quantity * item.unit_price, \"currency\": item.currency, \"product\": product.id \}"
The name of the mapping definition. Each mapping definition in your account must have a unique name.
Optional publishedThe UTC date and time when the mapping definition was last published, e.g. 2022-12-31T14:05:00Z
Optional sourceA schema describing the shape of the input JSON. The schema is not used to map documents, but it can provide valuable assistance while writing mapping expressions in the Mappings UI. The schema can include a default document with values that, also, can be helpful while writing mapping expressions. If you don't plan on editing the mapping definition using the UI, there's no benefit to including a source schema.
Optional targetA schema describing the shape of the output JSON. The schema is not used to map documents, but in the Mappings UI, you can only write mapping expressions for fields that are present in the target schema.
The schema can include a default document. When mapping_type is set to merge_with_target_example, the values in this document are used as defaults, i.e. if a mapping expressions doesn't produce a value for a given field, the default value is used. For the mapping type merge_with_target_example, providing a target schema with a default document is mandatory. For all other mapping types, the default document is ignored and the entire target schema is optional.
If you don't plan on editing the mapping definition using the UI, and you're using a mapping type other than merge_with_target_example, there's no benefit to including a target schema.
The mapping type, which determines the fields that show up in the output.
| Mapping type | Description |
|---|---|
| only_mapped_keys | Output fields are created based on the mapping expressions only. |
| merge_with_target_example | Output fields are copied from the target example, and created based on the mapping expressions. If both the target example and a mapping expression produce the same field, the field from the mapping expression takes precedence. Providing a target schema with a default document is mandatory. |
| pass_through | Output fields are copied from the input, and created based on the mapping expressions. If both the input and a mapping expression produce the same field, the field from the mapping expression takes precedence. |
The UTC date and time when the mapping definition was last updated, e.g. 2022-12-31T14:05:00Z. If it has never been updated, this is the same as the value for created_at.
The UTC date and time when the mapping definition was created, e.g.
2022-12-31T14:05:00Z