JSONata basics

JSONata  is a JSON query and transformation language. Mappings are pure JSONata expressions: input is the source row, output is the destination payload.

The mental model

• The whole expression is a single value — usually an object.
• Bare names are field lookups on the current context ($).
• . navigates into nested values; [] filters or maps arrays.
• $ prefixes a built-in function ($lowercase, $string, …).

Patterns you’ll use constantly

Renaming a field

{ "title": name }

Optional / fallback values

{ "vendor": manufacturer ? manufacturer : "Unknown" }

Mapping an array of children

{
  "variants": variants.{
    "sku": sku,
    "price": $string(price)
  }
}

The variants.{ … } form maps every element of variants through the template, returning an array.

Filtering an array

images[role = "main"].url

Returns the URLs of every image whose role is "main".

Concatenating strings

{ "handle": $lowercase(name & "-" & sku) }

Conditionals on the whole record

status = "enabled" ? {
  "title": name,
  "status": "ACTIVE"
} : {
  "title": name,
  "status": "ARCHIVED"
}

Escape hatches

If JSONata genuinely can’t express what you need, that’s a signal to talk to engineering — most “I need a loop with state” cases turn out to be a missing template helper, not a language limit.

Testing in the editor

The mapping editor has a built-in evaluator: paste an extracted source row into the Sample input panel and see the live output. Use real rows from a recent extract — synthetic samples lie.