JSONata Cheatsheet

Updated July 6, 2022

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

If you'd like to get started quickly but don't have a specific mapping in mind, consider 1-click importing one of the various mappings we provide for free in our starter-kit on Github. Navigate into a folder and click the "Run on Stedi" button which will import the full mapping into your Stedi account.

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"
    }
  ]
}

1.1 Retrieving data

Root-level field

Nested field in the root object

Nested field with a dash in its name in the root object

Nested field in a root level array

Retrieve an array of items from a root level array

Retrieve a root-level field with whitespace in its key

Retrieve a nested field with whitespace in its key

1.2 Operating on data

Concatenate two strings, separated by a space

Multiply two values retrieved from an array together

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

Remove a given character from a string

Convert a value to a string

Note: ($string is a JSONata function)

Convert a value to a number

Note: ($number is a JSONata function)

1.3 String manipulation

Convert a value to a lowercase string

Convert a value to an uppercase string

Truncate a string to only the first 4 characters

Check if a string contains a given substring

Get all characters in a string after a given substring

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

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

1.4 Conditionals

Use a conditional to return a value based on a condition

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

1.5 Filtering data

Filter data if a given value is greater than N

Filter data if a given value is equal to X

Filter data based on a complex condition

Note: 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 fields based on a substring value filter expression

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

Add up all values in an array

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

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

Note: $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.

Note: $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

Note: a multi-line expression needs to be wrapped in ()

[
  {
    "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
    }
  }
]