Map source record fields onto a destination schema declaratively, with per-field transforms, skips, and lookups.

map_fields

Maps each source record onto a destination schema from a declarative mapping definition — built for migrations.

When to use it

Use map_fields when many fields need renaming, per-field transforms, or conditional skips, and you want the mapping to live in reviewable YAML rather than one large expression. For a handful of computed fields, a plain transform is simpler.

Configuration

Key	Type	Required	Default	Description
`mapping_file`	string	One of `mapping_file` or `mapping`	—	Path to a mapping YAML file. The file may also define `default_attributes` and `skip_record`.
`mapping`	object	One of `mapping_file` or `mapping`	—	Inline mapping definition, keyed by source field.
`lookups`	object	No	—	Destination field → JSONata expression, either a string or `{ from, required }`. Evaluated per record; a `required` lookup that resolves to null drops the record.
`skip_if_missing`	string[]	No	—	Source fields that must be present; a record where any of them is null, undefined, or an empty string is dropped.

When neither mapping_file nor mapping is set, the step fails with map_fields step requires mapping_file or mapping config.

Mapping entries

Each key in mapping is a source field name. Its value takes one of three shapes:

String — the destination field name; the source value is copied as-is.
Object — a mapping entry with these keys:

Key	Type	Required	Default	Description
`field`	string	Yes	—	Destination field name. A value starting with `$` is evaluated as a JSONata expression to compute the destination field name per record.
`transform`	string	No	—	JSONata expression producing the value; the source record is available as `record`.
`skip`	string	No	—	JSONata condition; when truthy, this field is omitted for the record.
`path`	string	No	—	OData navigation path. The value is resolved to a destination ID through the task's `lookup_connector`, and the output field becomes `<field>@odata.bind` with the value `/<path>(<id>)`.
`type`	string	No	—	`number`, `date`, or `string`. Generates a typed transform: `number` wraps the value in `$number(...)`; `date` parses with `$dtFromFormat(...)` and emits an ISO string. Also generates a skip for null (and empty-string for `number`/`date`) values.
`format`	string	No	`yyyy-MM-dd`	Date parse format used with `type: date`.

Array — a list of strings or entry objects, mapping one source field to multiple destination fields.

Mapping file extras

A mapping_file YAML may also define:

default_attributes — an object of destination fields added to every output record unless the mapping already set them.
skip_record — a JSONata string evaluated before mapping, or an object with preprocess (before mapping) and postprocess (after mapping, with the built record available as processed_record). A truthy result drops the record.

These two keys are read from the mapping file only, not from an inline mapping config.

Example

name: map-contacts
connectors:
  source:
    type: csv
steps:
  - name: read_contacts
    type: call_method
    config:
      connector: source
      method: read
      args:
        resource: contacts
 
  - name: map_contact
    type: map_fields
    config:
      mapping:
        firstname: firstname
        lastname: lastname
        companyname:
          field: company
          transform: "$trim(record.company)"
          skip: "record.company = null"
        birthdate:
          field: birthdate
          type: date
          format: yyyy-MM-dd

Behavior notes

The output is a new record containing only mapped fields, lookup results, and default_attributes — unmapped source fields do not carry over.
Null and undefined values are omitted from the output rather than written as nulls.
Expressions in transform, skip, lookups, and skip_record are evaluated with the source record's fields at the top level, plus record, input, arguments, variables, steps, and job_config.
Record-level drops (skip_if_missing, a required lookup miss, or a truthy skip_record) emit nothing downstream for that record.
map_fields is exempt from the static-config JSONata lint: its object config intentionally embeds expression strings.

transform — a single expression instead of a mapping table
sync_record — write the mapped record idempotently
Idempotent sync and the mapping DB — where mapping fits in a migration pipeline