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"
}
]
}
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
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.
([-1] retrieves the last item in an array)
Remove a given character from a string
Convert a value to a string
($string is a JSONata
function)
Convert a value to a number
($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
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
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.
Use $map, $sum and ~> operator to add up all values in an array
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
Populate an object field using the built-in $$ variable for every item while looping over an array
Convert value to a string and store it in a variable
$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
()Multiply values across all items in an array and return a boolean flag based on the result
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
1.8 Dates
Get the current date & time in ISO 8601 format
Get the current date & time in 6-character EDI date format
Get the current date & time in 8-character EDI date format
Convert a date from yyyy/MM/dd format to DD/MM/YYYY
Get the month given a date in yyyy/MM/dd format
Convert a date taken from an array from yyyy/MM/dd format to DD-MM-YYYY
Convert epoch date to EDI date format
Convert given UTC date to America/New_York timezone
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
Retrieve an array of fields from a root-level array
Retrieve a nested value from a root-level array
Retrieve a value with a space in its key from a root-level array
2.2 Operating on data
The data operations expressions operate on the same basis as for the JSON object source documents.
2.3 String manipulation
The string manipulation expressions operate on the same basis as for the JSON object source documents.
2.4 Conditionals
The conditionals expressions operate on the same basis as for the JSON object source documents.
2.5 Filtering data
The data filtering 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.
Get an array of all items based on a filter expression
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 all items in an array based on a substring filter expression
$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
Sum up all items in an array
Sum up all items in an array based on a filter expression
Use $map, $sum and ~> operator to add up all values in an array
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.
Was this page helpful?