JSONata Cheatsheet

This functionality is available in a Stedi module. Contact us for details.

All mappings expressions are based on JSONata language - this page showcases its most important features useful when creating a mapping.

1. JSON object source document

The source for each example is derived from the following JSON:

{
  "senderName": "STEDI",
  "customerID": "997321",
  "shipmentID": 3312412,
  "shipment type": "ASAP",
  "address": {
    "street": "1234 Main St.",
    "city": "Los Angeles",
    "state": "CA",
    "country name": "USA",
    "is-europe": false
  },
  "orders": [
    {
      "orderDate": "2021/03/17",
      "productID": "DEG32",
      "quantity": 3,
      "pricePerUnit": 5,
      "volume": "10"
    },
    {
      "orderDate": "2021/10/12",
      "productID": "OIU98",
      "quantity": 100,
      "pricePerUnit": 1,
      "volume": "15"
    },
    {
      "orderDate": "2021/01/07",
      "productID": "PWE47",
      "quantity": 45,
      "pricePerUnit": 500,
      "volume": "35"
    }
  ]
}

It is not recommended to use JSONata for floating point arithmetic, such as financial calculations. Floating-point arithmetic can introduce rounding errors, which can accumulate and lead to incorrect results. Visit our JSONata Playground for an example. We recommend representing monetary values as integers (e.g. cents) and performing calculations on those integers.

orders[-1].quantity * orders[-1].pricePerUnit

Result: 22500

([-1] retrieves the last item in an array)

Remove a given character from a string

Input:

{
  "assigned_location_id": 3183479,
  "destination": {
    "id": 54433189,
    "zip": "K2P0V6",
    "city": "Ottawa",
    "email": "bob@customer.com",
    "phone": "(555)555-5555",
    "company": "",
    "country": "Canada",
    "address1": "123-Amoebobacterieae-St",
    "address2": "Unit 806",
    "province": "Ontario",
    "last_name": "Bobsen",
    "first_name": "Bob"
  },
  "line_items": [
    {
      "id": 123456789987,
      "shop_id": 3998762,
      "quantity": 3,
      "price": 32.78,
      "variant_id": 2385087,
      "line_item_id": 466157049,
      "inventory_item_id": 123456789987,
      "fulfillable_quantity": 1,
      "fulfillment_order_id": 1568020,
      "token": "",
      "position": 2
    },
    {
      "id": 123456789987,
      "shop_id": 3998762,
      "quantity": 2,
      "price": 12.98,
      "variant_id": 2385088,
      "line_item_id": 466157040,
      "inventory_item_id": 123456789987,
      "fulfillable_quantity": 1,
      "fulfillment_order_id": 1568021,
      "token": "",
      "position": 2
    },
    {
      "id": 123456789987,
      "shop_id": 3998762,
      "quantity": 3,
      "price": 9.92,
      "variant_id": 2385089,
      "line_item_id": 466157041,
      "inventory_item_id": 123456789987,
      "fulfillable_quantity": 1,
      "fulfillment_order_id": 1568022,
      "token": "",
      "position": 2
    }
  ],
  "order_id": 3183479,
  "request_status": "unsubmitted",
  "shop_id": 255858046,
  "status": "open",
  "assigned_location": {
    "zip": "K2P0V6",
    "city": "Ottawa",
    "name": "Bob Bobsen",
    "phone": "(555)555-5555",
    "address1": "123 Amoebobacterieae St",
    "address2": "Unit 806",
    "province": "Ontario",
    "location_id": 17232953366,
    "country_code": "CA"
  }
}

Expression:

$replace(destination.address1, "-", "")

Result:

"123AmoebobacterieaeSt"

Convert a value to a string

$string(shipmentID)

Result: "3312412"

($string is a JSONata function)

Convert a value to a number

$number(customerID)

Result: 997321

($number is a JSONata function)

1.3 String manipulation

Convert a value to a lowercase string

$lowercase(senderName)

Result: "stedi"

Convert a value to an uppercase string

$uppercase(address.street)

Result: "1234 MAIN ST."

Truncate a string to only the first 4 characters

$substring(address.street, 0, 4)

Result: "1234"

Check if a string contains a given substring

$contains(address.street, "Main")

Result: true

Get all characters in a string after a given substring

$substringAfter(address.street, "1234 ")

Result: "Main St."

Replace all `/`s with `-` in a string

$join($split(orders[0].orderDate, "/"), '-')

Result: "2021-03-17"

Replace all `/`s with `-` in in a string (using `~>` operator)

$split(orders[0].orderDate, "/") ~> $join('-')

Result: "2021-03-17"

1.4 Conditionals

Use a conditional to return a value based on a condition

address."is-europe" ? "EUR" : "USD"

Result: "USD"

Use a conditional with a function to return a value based on a condition

$count(orders) > 3 ? "LARGE" : "SMALL"

Result: "SMALL"

1.5 Filtering data

Filter data if a given value is greater than N

orders[quantity > 10]

Result:

[
  {
    "orderDate": "2021/10/12",
    "productID": "OIU98",
    "quantity": 100,
    "pricePerUnit": 1,
    "volume": "15"
  },
  {
    "orderDate": "2021/01/07",
    "productID": "PWE47",
    "quantity": 45,
    "pricePerUnit": 500,
    "volume": "35"
  }
]

Filter data if a given value is equal to X

orders[productID = "PWE47"].orderDate

Result: "2021/01/07"

Filter data based on a complex condition

orders[quantity * pricePerUnit > 200].productID[]

Result: ["PWE47"]

The [] is required at the end of an expression to convert the result to an array.

1.6 Counting data

Count fields based on a greater-than filter expression

$count(orders[quantity > 50])

Result: 1

Count fields based on a substring value filter expression

$count(orders[$substring(orderDate, 0, 4) = "2021"])

Result: 3

Count fields based on a substring value with `~>` operator

orders[$substring(orderDate, 0, 4) = "2021"] ~> $count

Result: 3

Add up all values in an array

$sum(orders.quantity)

Result: 148

Add up all values in an array with `~>` operator

orders[quantity > 10].quantity ~> $sum

Result: 145

Use `$map`, `$sum` and `~>` operator to add up all values in an array

$map(orders.volume, $number) ~> $sum

Result: 60

$map is used to convert all items in orders.volume array to a $number.

1.7 Variables

In JSONata, any name that starts with a $ is a variable (e.g. $streetName := address.street). A variable can be one of any type in JSONata's type system.

Built-in variables

$ – the variable with no name refers to the context value at any point in the input JSON hierarchy.
$$ – the root of the input JSON. You can use it to break out of the current context and navigate down a different path.

Convert a list of fields to the desired format using the built-in `$` variable

Input:

{
  "orders": [
    {
      "orderDate": "2021/03/17",
      "productID": "DEG32",
      "quantity": 3,
      "pricePerUnit": 5,
      "volume": "10"
    },
    {
      "orderDate": "2021/10/12",
      "productID": "OIU98",
      "quantity": 100,
      "pricePerUnit": 1,
      "volume": "15"
    }
  ],
  "address": {
    "is-europe": false,
    "street": "1234 Main St.",
    "city": "Los Angeles",
    "state": "CA",
    "country name": "USA"
  },
  "senderName": "STEDI",
  "customerID": "997321",
  "shipmentID": 3312412,
  "shipment type": "ASAP"
}

Expression:

orders.orderDate.{
  "originalDate": $,
  "date": $convertDateTime($, "yyyy/MM/dd", "yyyy-MM-dd")
}

Result:

[
  {
    "originalDate": "2021/03/17",
    "date": "2021-03-17"
  },
  {
    "originalDate": "2021/10/12",
    "date": "2021-10-12"
  }
]

Populate an object field using the built-in `$$` variable for every item while looping over an array

Input:

{
  "address": {
    "is-europe": false,
    "street": "1234 Main St.",
    "city": "Los Angeles",
    "state": "CA",
    "country name": "USA"
  },
  "orders": [
    {
      "orderDate": "2021/03/17",
      "productID": "DEG32",
      "quantity": 3,
      "pricePerUnit": 5,
      "volume": "10"
    },
    {
      "orderDate": "2021/10/12",
      "productID": "OIU98",
      "quantity": 100,
      "pricePerUnit": 1,
      "volume": "15"
    },
    {
      "orderDate": "2021/01/07",
      "productID": "PWE47",
      "quantity": 45,
      "pricePerUnit": 500,
      "volume": "35"
    }
  ],
  "senderName": "STEDI",
  "customerID": "997321",
  "shipmentID": 3312412,
  "shipment type": "ASAP"
}

Expression:

orders.{
  "productId": productID,
  "address": $$.address
}

Result:

[
  {
    "productId": "DEG32",
    "address": {
      "is-europe": false,
      "street": "1234 Main St.",
      "city": "Los Angeles",
      "state": "CA",
      "country name": "USA"
    }
  },
  {
    "productId": "OIU98",
    "address": {
      "is-europe": false,
      "street": "1234 Main St.",
      "city": "Los Angeles",
      "state": "CA",
      "country name": "USA"
    }
  },
  {
    "productId": "PWE47",
    "address": {
      "is-europe": false,
      "street": "1234 Main St.",
      "city": "Los Angeles",
      "state": "CA",
      "country name": "USA"
    }
  }
]

Convert value to a string and store it in a variable

$shipmentIDAsString := $string(shipmentID)

Result: "3312412"

$variableName := value is how assigns value to a JSONata $variableName variable

Count all items in an array and return a different result based on its size

(
  $ordersCount := $count(orders);
  $ordersCount > 2 ? "Large order" : "Small order"
)

Result: "Large order"

A multi-line expression needs to be wrapped in ()

Multiply values across all items in an array and return a boolean flag based on the result

(
  $orderCosts := $map(orders, function($order) {
     $order.quantity * $order.pricePerUnit
  });
  $orderCosts ~> $sum > 10000
)

Result: true

Positional variables

Positional variables binding can be used to determine at which position in the sequence the current context item is. It can be used following any map, filter or order-by stage in the path.

The variable is available for use within subsequent stages of the path (e.g. within filter predicates or a map operation) and goes out of scope at the end of the path expression.

Populate order title based on its index within the orders array

Input:

{
  "orders": [
    {
      "orderDate": "2021/03/17",
      "productID": "DEG32",
      "quantity": 3,
      "pricePerUnit": 5,
      "volume": "10"
    },
    {
      "orderDate": "2021/10/12",
      "productID": "OIU98",
      "quantity": 100,
      "pricePerUnit": 1,
      "volume": "15"
    }
  ],
  "senderName": "STEDI",
  "customerID": "997321",
  "shipmentID": 3312412,
  "shipment type": "ASAP"
}

Expression:

orders#$myIndex.{
  "productId": productID,
  "orderTitle": "Order #" & ($myIndex + 1)
}

Result:

[
  {
    "productId": "DEG32",
    "orderTitle": "Order #1"
  },
  {
    "productId": "OIU98",
    "orderTitle": "Order #2"
  }
]

1.8 Dates

Get the current date & time in ISO 8601 format

$now()

Example result: "2026-10-03T05:08:08.560Z"

Get the current date & time in 6-character EDI date format

$convertDateTime($now(), $dateTime.RFC3339Millis, $dateTime.EDIDate)

Example result: "261003"

Get the current date & time in 8-character EDI date format

$convertDateTime($now(), $dateTime.RFC3339Millis, $dateTime.EDIDateLong)

Example result: "20261003"

Convert a date from `yyyy/MM/dd` format to `DD/MM/YYYY`

$convertDateTime(orders[0].orderDate, "yyyy/MM/dd", "dd/MM/yyyy")

Result: "17/03/2021"

Get the month given a date in `yyyy/MM/dd` format

$convertDateTime(orders[1].orderDate, "yyyy/MM/dd", "MM")

Result: "10"

Convert a date taken from an array from `yyyy/MM/dd` format to `DD-MM-YYYY`

$convertDateTime(orders[-1].orderDate, "yyyy/MM/dd", "dd-MM-yyyy")

Result: "07-01-2021"

Convert epoch date to EDI date format

Input:

{ "epoch": 1648812955 }

Expression:

$convertDateTime($fromMillis(epoch * 1000), $dateTime.RFC3339Millis, $dateTime.EDIDateLong)

Result:

"20220401"

Convert given UTC date to `America/New_York` timezone

Input:

{ "date": "2022-04-01T11:48:58.451Z" }

Expression:

$convertDateTime(date, $dateTime.RFC3339Millis, $dateTime.RFC3339Millis, "UTC", "America/New_York" )

Result:

"2022-04-01T07:48:58.451-04:00"

2. JSON array-of-objects source document

The source for each example is derived from the following JSON:

[
  {
    "orderDate": "2021/10/12",
    "productID": "OIU98",
    "quantity": 100,
    "pricePerUnit": 1,
    "address": {
      "street": "1234 Main St.",
      "city": "Los Angeles",
      "state": "CA",
      "country name": "USA",
      "is-europe": false
    }
  },
  {
    "orderDate": "2021/01/07",
    "productID": "PWE47",
    "quantity": 45,
    "pricePerUnit": 500,
    "address": {
      "street": "La Rambla",
      "city": "Barcelona",
      "state": "Barcelona",
      "country name": "Spain",
      "is-europe": true
    }
  }
]

2.1 Retrieving data

Retrieve a field from the first item of a root-level array

$$[0].orderDate

Result: "2021/10/12"

Retrieve an array of fields from a root-level array

orderDate

Result: ["2021/10/12","2021/01/07"]

Retrieve a nested value from a root-level array

$$[1].address."is-europe"

Result: true

Retrieve a value with a space in its key from a root-level array

$$[0].address.`country name`

Result: "USA"

$$[quantity > 10]

Result:

[
  {
    "orderDate": "2021/10/12",
    "productID": "OIU98",
    "quantity": 100,
    "pricePerUnit": 1,
    "address": {
      "street": "1234 Main St.",
      "city": "Los Angeles",
      "state": "CA",
      "country name": "USA",
      "is-europe": false
    }
  },
  {
    "orderDate": "2021/01/07",
    "productID": "PWE47",
    "quantity": 45,
    "pricePerUnit": 500,
    "address": {
      "street": "La Rambla",
      "city": "Barcelona",
      "state": "Barcelona",
      "country name": "Spain",
      "is-europe": true
    }
  }
]

2.6 Counting data

The data counting expressions operate on the same basis as for the JSON object source documents.

Instead of selecting an array field, you can select the root array with the $$ selector.

Count all items in an array based on a greater-than filter expression

$count($$[quantity > 50])

Result: 1

Count all items in an array based on a substring filter expression

$count($$[$substring(orderDate, 0, 4) = "2021"])

Result: 2

$substring(orderDate, 0, 4) returns first four characters of a string)

Count all items in an array based on a substring filter expressions using `~>` operator

$$[$substring(orderDate, 0, 4) = "2021"] ~> $count

Result: 2

Sum up all items in an array

$sum(quantity)

Result: 145

Sum up all items in an array based on a filter expression

$$[quantity > 10].quantity ~> $sum

Result: 145

Use `$map`, `$sum` and `~>` operator to add up all values in an array

Input:

[
  {
    "orderDate": "2021/10/12",
    "volume": "10",
    "productID": "OIU98",
    "quantity": 100,
    "pricePerUnit": 1,
    "address": {
      "street": "1234 Main St.",
      "city": "Los Angeles",
      "state": "CA",
      "country name": "USA",
      "is-europe": false
    }
  },
  {
    "orderDate": "2021/01/07",
    "volume": "15",
    "productID": "PWE47",
    "quantity": 45,
    "pricePerUnit": 500,
    "address": {
      "street": "La Rambla",
      "city": "Barcelona",
      "state": "Barcelona",
      "country name": "Spain",
      "is-europe": true
    }
  }
]

Expression:

$map(volume, $number) ~> $sum

Result:

2.7 Variables

Variables operate on the same basis as for the JSON object source documents.

2.8 Dates

The dates expressions operate on the same basis as for the JSON object source documents.

JSONata Cheatsheet

On this page