What is JSONata?
JSONata is a query and transformation language for JSON, created at IBM and used in Node-RED, AWS Step Functions, Stedi, IBM App Connect and many integration platforms. A JSONata expression is a path like Account.Order.Product.Price that can also filter, compute, sort and build new JSON. Where JSONPath only selects values, JSONata can reshape a whole document into the format another API expects.
This playground runs the official jsonata 2.0 JavaScript library, so expressions behave the same as in Node.js and in tools built on it. Evaluation is asynchronous in JSONata 2, and the playground waits for the result, so async custom functions work too.
How to use the JSONata playground
- Paste or open a JSON document in the input box, or start with the orders sample.
- Type an expression in the box at the top. The result updates as you type.
- If the expression has a syntax error, the message shows the position of the problem.
- Add variables as a JSON object under Variable bindings. A binding
{"rate": 1.2}becomes$ratein your expression. - Copy the result, or click an example chip to see a common pattern.
JSONata syntax cheat sheet
| Expression | What it does |
|---|---|
Account.Name | Navigate into objects with dots. Missing paths return nothing instead of an error. |
Order[0], Order[-1] | First and last array item. |
Product[Price > 30] | Filter: keep items where the predicate is true. |
Product.(Price * Quantity) | Map: evaluate an expression for each item. |
Product.{ "name": `Product Name` } | Build a new object per item. Backticks quote field names with spaces. |
$sum(Product.Price) | Aggregate with $sum, $max, $min, $average, $count. |
Product^(>Price) | Sort descending by Price (< for ascending). |
Product{ SKU: Price } | Group-by: build an object keyed by SKU. |
"Hello " & Name | String concatenation uses &, not +. |
Price > 100 ? "high" : "low" | Conditional (ternary) expression. |
( $x := 5; $x * 2 ) | Block with a local variable binding. |
**.Price | Descendant wildcard: every Price at any depth. |
JSONata examples
Filter and reshape
Return the name and line total of every product that costs more than 30:
Account.Order.Product[Price > 30].{
"name": `Product Name`,
"total": Price * Quantity
}
Aggregate across nested arrays
JSONata flattens nested arrays automatically when you navigate, so the total value of every order is one call:
$sum(Account.Order.Product.(Price * Quantity))
Group by a field
Count quantity per colour across all orders. The { key: value } after a path groups matching items by key and evaluates the value per group:
Account.Order.Product{ Description.Colour: $sum(Quantity) }
Use a variable binding
With the binding {"rate": 0.9}, convert every price to another currency:
Account.Order.Product.{ "sku": SKU, "eur": $round(Price * $rate, 2) }
Common JSONata errors
- Result is empty. JSONata returns nothing (undefined) when a path does not match. Check spelling and case:
accountis notAccount. - A single item instead of an array. When a filter matches one item, JSONata returns that item, not a one-element array. Add
[]at the end of a path step, as inProduct[Price > 30][], to always get an array. - Field names with spaces or dashes. Wrap them in backticks:
`Product Name`. - T2001 / T2002: argument must be a number. Arithmetic on strings fails. Convert with
$number(Price)first. - Using + to join strings. Use
&for strings.+is only for numbers.
JSONata vs JSONPath vs jq
JSONPath is a selection language: it returns existing values and is what tools like Kubernetes and Postman accept as a path. jq is a command-line language with a pipeline style that suits shell scripts. JSONata sits in between: it reads like a path, but it can compute, aggregate and construct new JSON, and it is designed to be embedded in JavaScript applications and low-code tools. If you are writing a mapping for Node-RED, AWS Step Functions or an integration platform, JSONata is usually what that platform expects.
To check the shape of your output, paste it into the JSON viewer, or validate it against a contract with the JSON Schema validator.
Frequently asked questions
What is JSONata used for?
JSONata queries and transforms JSON. It is used in Node-RED function nodes, AWS Step Functions (JSONata query language), IBM App Connect, and many integration and low-code tools to map one JSON structure into another.
Which JSONata version does this playground use?
It loads the official jsonata 2.0.6 library from npm via jsDelivr. JSONata 2 makes evaluate() asynchronous, which the playground handles for you.
How do I always get an array from a JSONata expression?
Add empty square brackets to the path step, for example Product[Price > 30][]. Without them, a filter that matches one item returns the item itself rather than a one-element array.
How do I reference a field name with a space in JSONata?
Wrap the name in backticks, for example `Product Name`. The same applies to names containing dashes or other characters that are not valid in a plain path.
How do I pass variables into a JSONata expression?
Enter a JSON object in the Variable bindings box. Each key becomes a variable, so {"rate": 1.2} is available as $rate. In code, pass the same object as the second argument to expression.evaluate(data, bindings).
Is my JSON sent to a server?
No. The JSONata engine runs in your browser. Your JSON and expressions never leave your device.