Language overview
JSONata is a query and transformation language for JSON. An expression selects values from a
document with location paths (Account.Order.Product), combines them with operators and
functions ($sum(Product.(Price * Quantity))), and shapes the output with ordinary JSON syntax
({"total": ...}). It also has variables, functions and conditionals, so rules of any
complexity can be written in it.
jlens implements JSONata 2.2 and is checked against the official test suite. Where it differs from the reference implementation, jsonata-js, Compatibility says so.
This reference is adapted from the JSONata documentation (© IBM Corp. and JSONata contributors, MIT license), reorganized and extended with jlens-specific notes. Every example in it is run against jlens by
cargo xtask doc-check.
Reading the examples
Examples show an expression followed by its result after =>:
1 + 2
=> 3
When an example needs an input document, its first line names it. Most examples use one of three sample documents, listed at the end of this page:
input: address.json
Address.City
=> "Winchester"
A result of undefined means the expression produced nothing: JSONata’s empty sequence. The
command line prints nothing for it, and the APIs return None or undefined.
Types
JSONata values have the JSON types plus one more:
| Type | Examples |
|---|---|
| string | "hello", 'hello' |
| number | 42, -3.5, 1e6 (always a 64-bit float) |
| Boolean | true, false |
| null | null |
| array | [1, "two", null] |
| object | {"name": "Fred", "age": 28} |
| function | $uppercase, function($x) { $x * 2 } |
JSONata is a superset of JSON. Every JSON document is a valid expression that evaluates to itself. A JSON template is therefore a good start for a transformation: replace its values with expressions.
input: address.json
{"name": FirstName & " " & Surname, "adult": Age >= 18, "phones": $count(Phone)}
=> {"name": "Fred Smith", "adult": true, "phones": 4}
Sequences
A path can match zero, one or many values, so JSONata expressions produce sequences. The rules for sequences shape every result:
- An empty sequence is nothing. It is not
null, and it does not appear in the output: an object field whose value is an empty sequence is left out. - A sequence of one value is that value. No array surrounds it.
- A sequence of several values is output as an array.
- Sequences are flattened. Values of nested sequences are pulled up into the outer one.
Arrays from the input, or built with
[...], keep their structure.
input: address.json
Phone[type = 'mobile'].number
=> "077 7700 1234"
input: address.json
Phone[type = 'office'].number
=> ["01962 001234", "01962 001235"]
input: address.json
{"fax": Phone[type = 'fax'].number, "name": FirstName}
=> {"name": "Fred"}
The second rule makes a single value and a one-element array interchangeable, which keeps
expressions composable. When a consistent array is needed, the
[] modifier keeps singleton results as arrays.
Comments
/* ... */ comments can appear anywhere whitespace can:
input: address.json
/* the person's full name */
FirstName & " " & Surname
=> "Fred Smith"
Comments that start with /** are documentation comments. jlens reads @label, @message
and @id tags in them to describe checks in audits; see
Audit annotations. Other JSONata implementations treat them as ordinary
comments.
The rest of this reference
- Paths: navigating objects and arrays, predicates, wildcards, and the path
stages (
#,@,%). - Building results: array and object constructors.
- Operators: arithmetic, comparison, Boolean, string, conditional and chaining operators, and their precedence.
- Sorting, grouping and aggregation.
- Programming: variables, blocks, functions, recursion, closures, partial application, function composition and the transform operator.
- Regular expressions and Dates and times.
- The function library, with a page per category.
- Errors: every error code.
Sample documents
address.json:
{
"FirstName": "Fred",
"Surname": "Smith",
"Age": 28,
"Address": {
"Street": "Hursley Park",
"City": "Winchester",
"Postcode": "SO21 2JN"
},
"Phone": [
{ "type": "home", "number": "0203 544 1234" },
{ "type": "office", "number": "01962 001234" },
{ "type": "office", "number": "01962 001235" },
{ "type": "mobile", "number": "077 7700 1234" }
],
"Email": [
{
"type": "work",
"address": ["fred.smith@my-work.com", "fsmith@my-work.com"]
},
{
"type": "home",
"address": ["freddy@my-social.com", "frederic.smith@very-serious.com"]
}
],
"Other": {
"Over 18 ?": true,
"Misc": null,
"Alternative.Address": {
"Street": "Brick Lane",
"City": "London",
"Postcode": "E1 6RF"
}
}
}
invoice.json:
{
"Account": {
"Account Name": "Firefly",
"Order": [
{
"OrderID": "order103",
"Product": [
{
"Product Name": "Bowler Hat",
"ProductID": 858383,
"SKU": "0406654608",
"Description": {
"Colour": "Purple",
"Width": 300,
"Height": 200,
"Depth": 210,
"Weight": 0.75
},
"Price": 34.45,
"Quantity": 2
},
{
"Product Name": "Trilby hat",
"ProductID": 858236,
"SKU": "0406634348",
"Description": {
"Colour": "Orange",
"Width": 300,
"Height": 200,
"Depth": 210,
"Weight": 0.6
},
"Price": 21.67,
"Quantity": 1
}
]
},
{
"OrderID": "order104",
"Product": [
{
"Product Name": "Bowler Hat",
"ProductID": 858383,
"SKU": "040657863",
"Description": {
"Colour": "Purple",
"Width": 300,
"Height": 200,
"Depth": 210,
"Weight": 0.75
},
"Price": 34.45,
"Quantity": 4
},
{
"ProductID": 345664,
"SKU": "0406654603",
"Product Name": "Cloak",
"Description": {
"Colour": "Black",
"Width": 30,
"Height": 20,
"Depth": 210,
"Weight": 2
},
"Price": 107.99,
"Quantity": 1
}
]
}
]
}
}
library.json:
{
"library": {
"books": [
{
"title": "Structure and Interpretation of Computer Programs",
"authors": ["Abelson", "Sussman"],
"isbn": "9780262510875",
"price": 38.90,
"copies": 2
},
{
"title": "The C Programming Language",
"authors": ["Kernighan", "Richie"],
"isbn": "9780131103627",
"price": 33.59,
"copies": 3
},
{
"title": "The AWK Programming Language",
"authors": ["Aho", "Kernighan", "Weinberger"],
"isbn": "9780201079814",
"copies": 1
},
{
"title": "Compilers: Principles, Techniques, and Tools",
"authors": ["Aho", "Lam", "Sethi", "Ullman"],
"isbn": "9780201100884",
"price": 23.38,
"copies": 1
}
],
"loans": [
{
"customer": "10001",
"isbn": "9780262510875",
"return": "2016-12-05"
},
{
"customer": "10003",
"isbn": "9780201100884",
"return": "2016-10-22"
},
{
"customer": "10003",
"isbn": "9780262510875",
"return": "2016-12-22"
}
],
"customers": [
{
"id": "10001",
"name": "Joe Doe",
"address": {
"street": "2 Long Road",
"city": "Winchester",
"postcode": "SO22 5PU"
}
},
{
"id": "10002",
"name": "Fred Bloggs",
"address": {
"street": "56 Letsby Avenue",
"city": "Winchester",
"postcode": "SO22 4WD"
}
},
{
"id": "10003",
"name": "Jason Arthur",
"address": {
"street": "1 Preddy Gate",
"city": "Southampton",
"postcode": "SO14 0MG"
}
}
]
}
}