> ## Documentation Index
> Fetch the complete documentation index at: https://stedi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# JSONata Cheatsheet
This functionality is available in a Stedi module. [Contact us](https://www.stedi.com/contact) for details.
All mappings expressions are based on [JSONata language](http://docs.jsonata.org/overview.html) - 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:
```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](https://stedi.link/UKXfsxe) 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](/edi-platform/mappings/jsonata/jsonata-functions/string#dollarstring))
#### Convert a value to a number
(`$number` is a [JSONata
function](/edi-platform/mappings/jsonata/jsonata-functions/numeric#dollarnumber))
### 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](https://stedi.link/UKXfsxe) 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
[\$map](/edi-platform/mappings/jsonata/jsonata-functions/higher-order#dollarmap)
is used to convert all items in `orders.volume` array to a
[\$number](/edi-platform/mappings/jsonata/jsonata-functions/numeric#dollarnumber).
### 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](https://docs.jsonata.org/processing#the-jsonata-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
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
#### Positional variables
[Positional variables binding](https://docs.jsonata.org/path-operators#-positional-variable-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:
```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](#12-operating-on-data).
### 2.3 String manipulation
The string manipulation expressions operate on the same basis as for the [JSON object source documents](#13-string-manipulation).
### 2.4 Conditionals
The conditionals expressions operate on the same basis as for the [JSON object source documents](#14-conditionals).
### 2.5 Filtering data
The data filtering expressions operate on the same basis as for the [JSON object source documents](#15-filtering-data).
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](#16-counting-data).
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](#17-variables).
### 2.8 Dates
The dates expressions operate on the same basis as for the [JSON object source documents](#18-dates).