JSONata

https://docs.jsonata.org/
Admin
JSONata is a lightweight query and transformation language for JSON data, inspired by XPath 3.1,...
Tokens:52,861
Snippets:369
Trust Score:8.7
Update:1 hour ago
Show doc for...
Tokens:
Raw
### Install JSONata from npm

Source: https://docs.jsonata.org/using-nodejs

Install the JSONata package using npm.

```bash
npm install jsonata
```

--------------------------------

### Output of closure example

Source: https://docs.jsonata.org/programming

The result produced by the closure example, showing the account name and product SKU mappings.

```json
{
  "Account": "Firefly",
  "SKU-858383": "Bowler Hat",
  "SKU-345664": "Cloak"
}
```

--------------------------------

### $substring(str, start[, length])

Source: https://docs.jsonata.org/string-functions

Returns a string containing the characters in the first parameter str starting at position start (zero-offset). If str is not specified, the context value is used. An error is thrown if str is not a string. If length is specified, the substring will contain maximum length characters. If start is negative, it indicates the number of characters from the end of str.

```APIDOC
## $substring(str, start[, length])

### Description
Returns a string containing the characters in the first parameter `str` starting at position `start` (zero-offset). If `str` is not specified (i.e. this function is invoked with only the numeric argument(s)), then the context value is used as the value of `str`. An error is thrown if `str` is not a string.

If `length` is specified, then the substring will contain maximum `length` characters.

If `start` is negative then it indicates the number of characters from the end of `str`. See substr for full definition.

### Parameters
- **str** (string) - Optional - The source string. If omitted, the context value is used.
- **start** (number) - Required - The zero-based starting position. If negative, indicates the number of characters from the end of `str`.
- **length** (number) - Optional - The maximum number of characters to include.

### Examples
- `$substring("Hello World", 3)` => `"lo World"`
- `$substring("Hello World", 3, 5)` => `"lo Wo"`
- `$substring("Hello World", -4)` => `"orld"`
- `$substring("Hello World", -4, 2)` => `"or"`
```

--------------------------------

### $reverse() examples

Source: https://docs.jsonata.org/array-functions

Returns the array in reverse order. The second example uses the pipe operator ~>.

```jsonata
$reverse(["Hello", "World"])
```

```jsonata
[1..5] ~> $reverse()
```

--------------------------------

### $zip() examples

Source: https://docs.jsonata.org/array-functions

Returns a zipped array of grouped values from the arguments. The length is determined by the shortest array.

```jsonata
$zip([1,2,3], [4,5,6])
```

```jsonata
$zip([1,2,3],[4,5],[7,8,9])
```

--------------------------------

### Function invocation examples

Source: https://docs.jsonata.org/programming

Examples of invoking built-in functions with arguments. $uppercase returns the string in uppercase, $substring returns a substring, and $sum returns the sum of an array.

```jsonata
$uppercase("Hello")
```

```jsonata
$substring("hello world", 0, 5)
```

```jsonata
$sum([1,2,3])
```

--------------------------------

### $map() basic example with output

Source: https://docs.jsonata.org/higher-order-functions

Applies a lambda function to each element of an array. For an array of 2 or more elements, returns an array of results. The example shows $map([1,2,3], function($v) { $v * 2 }) evaluating to [ 2, 4, 6 ].

```jsonata
$map([1,2,3], function($v) { $v * 2 })
```

```json
[ 2, 4, 6 ]
```

--------------------------------

### Example: matching products with 'hat' in name

Source: https://docs.jsonata.org/regex

Matches all products that have 'hat' in their name, case-insensitive due to the 'i' flag.

```jsonata
Account.Order.Product[`Product Name` ~> /hat/i ]
```

--------------------------------

### $shuffle() example

Source: https://docs.jsonata.org/array-functions

Returns the array shuffled into random order. The output is non-deterministic.

```jsonata
$shuffle([1..9])
```

--------------------------------

### $append() examples

Source: https://docs.jsonata.org/array-functions

Returns an array with values from array1 followed by array2. Non-array parameters are treated as singleton arrays.

```jsonata
$append([1,2,3], [4,5,6])
```

```jsonata
$append([1,2,3], 4)
```

```jsonata
$append("Hello", "World")
```

--------------------------------

### $filter() example with lambda

Source: https://docs.jsonata.org/higher-order-functions

Returns an array containing only values that satisfy the predicate function. The example filters products whose price is higher than the average price.

```jsonata
$filter(Account.Order.Product, function($v, $i, $a) {
  $v.Price > $average($a.Price)
})
```

--------------------------------

### $match() example with regex /a(b+)/

Source: https://docs.jsonata.org/string-functions

Applies the regex /a(b+)/ to the string "ababbabbcc" and returns an array of match objects. Each object contains the matched substring, its zero-based index, and an array of captured groups.

```jsonata
$match("ababbabbcc",/a(b+)/)
```

```json
[
  {
    "match": "ab",
    "index": 0,
    "groups": ["b"]
  },
  {
    "match": "abb",
    "index": 2,
    "groups": ["bb"]
  },
  {
    "match": "abb",
    "index": 5,
    "groups": ["bb" ]
  }
]
```

--------------------------------

### $distinct() examples

Source: https://docs.jsonata.org/array-functions

Removes duplicates based on deep equality. The second example uses a path expression.

```jsonata
$distinct([1,2,3,3,4,3,5])
```

```jsonata
$distinct(Account.Order.Product.Description.Colour)
```

--------------------------------

### Transform with Delete Clause

Source: https://docs.jsonata.org/other-operators

Example showing how to remove properties using the optional `delete` clause.

```APIDOC
## Transform with Delete Clause

### Description
Copies the input, but for each matched object, inserts a `Total` and removes the specified properties.

### Example
`$ ~> |Account.Order.Product|{'Total': Price * Quantity}, ['Price', 'Quantity']|`

This copies the input, but for each `Product` it inserts a `Total` and removes the `Price` and `Quantity` properties.
```

--------------------------------

### Multiple Updates in Transform

Source: https://docs.jsonata.org/other-operators

Example showing multiple updates (inserts or updates) in a single transform, similar to `$merge()`.

```APIDOC
## Multiple Updates in Transform

### Description
Allows multiple changes to be made to an object in one transform.

### Example
`|Account.Order.Product|{'Price': Price * 1.2, 'Total': Price * Quantity}|`

This updates `Price` and adds a `Total` field. Note: `Total` is calculated using the original `Price`, not the modified one (JSONata is declarative).
```

--------------------------------

### Register a custom function with registerFunction()

Source: https://docs.jsonata.org/embedding-extending

Permanently binds a function to a name in the expression. The example registers 'greet' and evaluates it to return 'Hello world'.

```javascript
var expression = jsonata("$greet()");
expression.registerFunction("greet", () => "Hello world");

await expression.evaluate({}); // "Hello world"
```

--------------------------------

### Higher order function example: $twice

Source: https://docs.jsonata.org/programming

Demonstrates a higher order function that takes a function and returns a new function applying the input function twice. The example defines $twice, $add3, and $add6, then invokes $add6(7) to return 13.

```jsonata
(
  $twice := function($f) { function($x){ $f($f($x)) } };
  $add3 := function($y){ $y + 3 };
  $add6 := $twice($add3);
  $add6(7)
)
```

--------------------------------

### $count() examples

Source: https://docs.jsonata.org/array-functions

Returns the number of items in an array. Non-array values are treated as singleton arrays. If array is omitted, the context value is used.

```jsonata
$count([1,2,3,1])
```

```jsonata
$count("hello")
```

--------------------------------

### $map() with lambda using index and array

Source: https://docs.jsonata.org/higher-order-functions

Uses a user-defined lambda function with parameters $v, $i, and $a to build strings that include the index and total count. The example shows $map(Email.address, ...) evaluating to an array of formatted strings.

```jsonata
$map(Email.address, function($v, $i, $a) {
   'Item ' & ($i+1) & ' of ' & $count($a) & ': ' & $v
})
```

```json
[
  "Item 1 of 4: fred.smith@my-work.com",
  "Item 2 of 4: fsmith@my-work.com",
  "Item 3 of 4: freddy@my-social.com",
  "Item 4 of 4: frederic.smith@very-serious.com"
]
```

--------------------------------

### $single() example: find product by SKU

Source: https://docs.jsonata.org/higher-order-functions

Returns the only product in Account.Order.Product whose SKU equals "0406654608". Throws an exception if the number of matching values is not exactly one. The predicate function receives value, index, and array parameters.

```jsonata
$single(Account.Order.Product, function($v, $i, $a) {
  $v.SKU = "0406654608"
})
```

--------------------------------

### $now()

Source: https://docs.jsonata.org/date-time

Returns the current date/time timestamp as an ISO 8601 formatted string. The timestamp is captured at the start of expression evaluation and is the same for all occurrences within the same expression.

```APIDOC
## $now()

### Description
Returns the current date/time timestamp as an ISO 8601 formatted string. The timestamp is captured at the start of the expression evaluation and is the same for every occurrence of `$now()` in the same expression.

### Method
Function

### Endpoint
`$now()`

### Parameters
None

### Return Value
- **timestamp** (string) - ISO 8601 formatted date/time string.

### Example
```
{ "invoiceTime": $now(), "total": $sum(Account.Order.Product.(Price * Quantity)), "closingTime": $now() }
```

### Response Example
```
{ "invoiceTime": "2018-12-10T13:49:51.141Z", "total": 336.36, "closingTime": "2018-12-10T13:49:51.141Z" }
```
```

--------------------------------

### Variable scope example

Source: https://docs.jsonata.org/programming

Shows variable binding within a block. The variables $p and $q are scoped to the block and used to calculate the product of Price and Quantity.

```jsonata
Invoice.(
  $p := Product.Price;
  $q := Product.Quantity;
  $p * $q
)
```

--------------------------------

### Closure example: capturing Account context

Source: https://docs.jsonata.org/programming

Shows a lambda function capturing the context item at definition time. When invoked later with a different context, it still uses the stored environment, demonstrating lexical scoping.

```jsonata
Account.(
  $AccName := function() { $.'Account Name' };

  Order[OrderID = 'order104'].Product.{
    'Account': $AccName(),
    'SKU-' & $string(ProductID): $.'Product Name'
  }
)
```

--------------------------------

### Example HTML page using JSONata in browser

Source: https://docs.jsonata.org/using-browser

An HTML page that loads JSONata from a CDN and evaluates a JSONata expression on user input. The expression '"Hello, " & name' is evaluated asynchronously using the jsonata() function, and the result is displayed in a paragraph element.

```HTML
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>JSONata test</title>
    <script src="https://cdn.jsdelivr.net/npm/jsonata/jsonata.min.js"></script>
    <script>
      async function greeting() {
        var json = JSON.parse(document.getElementById('json').value);
        var result = await jsonata('"Hello, " & name').evaluate(json);
        document.getElementById('greeting').innerHTML = result;
      }
    </script>
  </head>
  <body>
    <textarea id="json">{ "name": "Wilbur" }</textarea>
    <button onclick="greeting()">Click me</button>
    <p id="greeting"></p>
  </body>
</html>
```

--------------------------------

### Formatting and parsing custom date/time formats with picture strings

Source: https://docs.jsonata.org/date-time

Demonstrates using $toMillis() and $fromMillis() with picture string notation to convert between custom date formats. The first example shows US and European date formats, and the second shows a more verbose format.

```jsonata
 $toMillis('10/12/2018', '\[D\]/\[M\]/\[Y\]') ~> $fromMillis('\[M\]/\[D\]/\[Y\]')
```

```json
 "12/10/2018"
```

```jsonata
 $toMillis('10/12/2018', '\[D\]/\[M\]/\[Y\]') ~> $fromMillis('\[FNn\], \[D1o\] \[MNn\] \[YI\]')
```

```json
 "Monday, 10th December MMXVIII"
```

--------------------------------

### Evaluate with bindings in evaluate()

Source: https://docs.jsonata.org/embedding-extending

Passes variable bindings to evaluate(). The example binds a and b, where b is a function, and returns 82.

```javascript
await jsonata("$a + $b()").evaluate({}, {a: 4, b: () => 78});
// returns 82
```

--------------------------------

### Node.js application using JSONata

Source: https://docs.jsonata.org/using-nodejs

Example Node.js application that requires jsonata, defines a data object, and evaluates the expression '$sum(example.value)' asynchronously, returning 24.

```javascript
const jsonata = require('jsonata');

const data = {
    example: [
        {value: 4},
        {value: 7},
        {value: 13}
    ]
};

(async () => {
    const expression = jsonata('$sum(example.value)');
    const result = await expression.evaluate(data);  // returns 24
})()
```

--------------------------------

### $sift() example filtering object keys by regex

Source: https://docs.jsonata.org/higher-order-functions

Sifts each Product object to retain only fields whose keys match the regex /^Product/. The predicate receives the value and key. The output shows the resulting array of objects with only the matching fields.

```jsonata
Account.Order.Product.$sift(function($v, $k) {$k ~> /^Product/})
```

```json
[
  {
    "Product Name": "Bowler Hat",
    "ProductID": 858383
  },
  {
    "Product Name": "Trilby hat",
    "ProductID": 858236
  },
  {
    "Product Name": "Bowler Hat",
    "ProductID": 858383
  },
  {
    "ProductID": 345664,
    "Product Name": "Cloak"
  }
]
```

--------------------------------

### $reduce() example: multiply array values

Source: https://docs.jsonata.org/higher-order-functions

Multiplies all values in the array [1..5] to return 120. The supplied function acts as an infix operator between values, with the accumulator as the first argument. The optional init parameter sets the initial aggregation value; otherwise the first array value is used.

```jsonata
(
  $product := function($i, $j){$i * $j};
  $reduce([1..5], $product)
)
```

--------------------------------

### Asynchronous evaluation with callback

Source: https://docs.jsonata.org/embedding-extending

When a callback is supplied, evaluate() returns undefined and runs asynchronously. The example prints 'Started' then 'Finished with 19'.

```javascript
await jsonata("7 + 12").evaluate({}, {}, (error, result) => {
  if(error) {
    console.error(error);
    return;
  }
  console.log("Finished with", result);
});
console.log("Started");

// Prints "Started", then "Finished with 19"
```

--------------------------------

### Partial Application with Composition: $first5Capitalized

Source: https://docs.jsonata.org/programming

Combines partial application and function composition to create a function that takes the first 5 characters and uppercases them. Applied to Address.City, it yields 'WINCH'.

```jsonata
( $first5Capitalized := $substring(?, 0, 5) ~> $uppercase(?); $first5Capitalized(Address.City) )
```

--------------------------------

### Partial application of $substring with ? placeholder

Source: https://docs.jsonata.org/programming

Creates a function $first5 by partially applying $substring with the first argument as a placeholder. Invoking $first5("Hello, World") returns "Hello".

```jsonata
( $first5 := $substring(?, 0, 5); $first5("Hello, World") )
```

--------------------------------

### $map() single-element array example with output

Source: https://docs.jsonata.org/higher-order-functions

For an array with 1 element, $map() returns the single result of applying the function. The example shows $map([2], function($v) { $v * 2 }) evaluating to 4.

```jsonata
$map([2], function($v) { $v * 2 })
```

```json
4
```

--------------------------------

### Transform Assigned to Variable

Source: https://docs.jsonata.org/other-operators

Example of assigning a transform to a variable for reuse.

```APIDOC
## Transform Assigned to Variable

### Description
Assigns a transform function to a variable for multiple uses.

### Example
`$increasePrice := |Account.Order.Product|{'Price': Price * 1.2}|`

Now `$increasePrice` can be called as a function on any object.
```

--------------------------------

### $now()

Source: https://docs.jsonata.org/date-time-functions

Generates a UTC timestamp in ISO 8601 compatible format and returns it as a string. All invocations within an expression return the same value. Optional picture and timezone parameters format the timestamp as described by $fromMillis().

```APIDOC
## $now()

### Description
Generates a UTC timestamp in ISO 8601 compatible format and returns it as a string. All invocations of `$now()` within an evaluation of an expression will all return the same timestamp value.

### Signature
`$now([picture [, timezone]])`

### Parameters
#### Optional Parameters
- **picture** (string) - Optional - Format picture string as described by `$fromMillis()`.
- **timezone** (string) - Optional - Timezone string in the format "±HHMM".

### Return Value
- **string** - The current UTC timestamp in ISO 8601 format, or formatted according to the picture and timezone parameters.

### Examples
- `$now()` => `"2017-05-15T15:12:59.152Z"`
```

--------------------------------

### Further partial application of $substring

Source: https://docs.jsonata.org/programming

Shows that a partially applied function can be further partially applied. $firstN is created with placeholders, then $first5 is derived from it, and invoking $first5("Hello, World") returns "Hello".

```jsonata
( $firstN := $substring(?, 0, ?); $first5 := $firstN(?, 5); $first5("Hello, World") )
```

--------------------------------

### $pad()

Source: https://docs.jsonata.org/string-functions

Returns a copy of the string with extra padding so its total length is at least the absolute value of the width parameter. Positive width pads to the right, negative width pads to the left. The optional char argument specifies the padding character(s), defaulting to space.

```APIDOC
## $pad()

### Description
Returns a copy of the string `str` with extra padding, if necessary, so that its total number of characters is at least the absolute value of the `width` parameter. If `width` is positive, the string is padded to the right; if negative, padded to the left. The optional `char` argument specifies the padding character(s), defaulting to space.

### Signature
`$pad(str, width [, char])`

### Parameters
- **str** (string) - Required - The string to pad.
- **width** (number) - Required - The minimum total length. Positive pads right, negative pads left.
- **char** (string) - Optional - The padding character(s) to use. Defaults to space.

### Examples
- `$pad("foo", 5)` => `"foo "`
- `$pad("foo", -5)` => `" foo"`
- `$pad("foo", -5, "#")` => `"##foo"`
- `$formatBase(35, 2) ~> $pad(-8, '0')` => `"00100011"`

```

--------------------------------

### Ackermann function in JSONata

Source: https://docs.jsonata.org/guardrails

Example recursive JSONata expression that can hit the stack guardrail when invoked with larger arguments.

```jsonata
(
  $ack := function($m, $n) {
    $m = 0 ? $n + 1 :
    $n = 0 ? $ack($m - 1, 1) :
    $ack($m - 1, $ack($m, $n - 1))
  };

  $ack(3, 4)
)
```

--------------------------------

### $string(arg, prettify)

Source: https://docs.jsonata.org/string-functions

Casts the arg parameter to a string using JSON.stringify rules. Functions become empty strings, numeric infinity and NaN throw errors, and other values are JSON-stringified. If arg is omitted, the context value is used. If prettify is true, the JSON output is indented with one line per field.

```APIDOC
## $string(arg, prettify)

### Description
Casts the `arg` parameter to a string using the following casting rules:
- Strings are unchanged
- Functions are converted to an empty string
- Numeric infinity and NaN throw an error because they cannot be represented as a JSON number
- All other values are converted to a JSON string using the JSON.stringify function

If `arg` is not specified (i.e. this function is invoked with no arguments), then the context value is used as the value of `arg`.

If `prettify` is true, then "prettified" JSON is produced. i.e One line per field and lines will be indented based on the field depth.

### Parameters
- **arg** (any) - Optional - The value to cast to a string. If omitted, the context value is used.
- **prettify** (boolean) - Optional - If true, produces prettified JSON output.

### Examples
- `$string(5)` => `"5"`
- `[1..5].$string()` => `["1", "2", "3", "4", "5"]`
```

--------------------------------

### Inline Transform Usage

Source: https://docs.jsonata.org/other-operators

Example of using the transform operator inline with the `~>` operator to apply a transformation directly to an object.

```APIDOC
## Inline Transform Usage

### Description
Applies a transform directly to an object using the `~>` operator.

### Example
`payload ~> |Account.Order.Product|{'Price': Price * 1.2}|`

This returns a deep copy of `payload` with each `Product`'s `Price` increased by 20%.
```

--------------------------------

### Recursive function example

Source: https://docs.jsonata.org/programming

Defines a recursive factorial function using a variable reference and invokes it with 4, returning 24.

```jsonata
( $factorial:= function($x){ $x <= 1 ? 1 : $x \* $factorial($x-1) }; $factorial(4) )
```

--------------------------------

### Binding a regex matcher to a variable

Source: https://docs.jsonata.org/regex

The regex syntax evaluates to a function. This example binds the matcher function to a variable $matcher.

```jsonata
$matcher := /[a-z]*an[a-z]*/i
```

--------------------------------

### Run-time error object from evaluate()

Source: https://docs.jsonata.org/embedding-extending

Example of the Error object thrown at run time, containing code, position, token, and message.

```json
{
  code: "T1006",
  stack: "...",
  position: 14,
  token: "notafunction",
  message: "Attempted to invoke a non-function"
}
```

--------------------------------

### Invocation Chaining Example: Customer.Email

Source: https://docs.jsonata.org/programming

Chains functions to process an email string: extracts substring after '@', then before '.', then uppercases. Equivalent to nested function calls.

```jsonata
Customer.Email ~> $substringAfter("@") ~> $substringBefore(".") ~> $uppercase()
```

--------------------------------

### $replace() with regex pattern

Source: https://docs.jsonata.org/string-functions

Uses the regex /a.*?a/ to match substrings starting and ending with 'a' and replaces them with '*'. The result is "*c*bra".

```jsonata
$replace("abracadabra", /a.*?a/, "*")
```

```jsonata
"*c*bra"
```

--------------------------------

### First match result object

Source: https://docs.jsonata.org/regex

The structure returned by the matcher function for the first match, including match, start, end, groups, and next function.

```json
{
  "match": "man",
  "start": 2,
  "end": 4,
  "groups": [],
  "next": "<native function>#0"
}
```
Tokens:
Raw