---
alias: user-guide-automation-converter-jsonata
description: "This converter evaluates a JSONata expression against a JSON value and returns the transformed result"
---

# JSONata

This converter applies a [JSONata](https://jsonata.org/) expression to the input value and returns the evaluated result. Use it to extract specific properties, filter, or transform JSON data flowing between tasks without chaining several converters.

The input must be a JSON object. A JSON string is also accepted and is parsed automatically before the expression is evaluated.

## Settings

| Name       | Data Type | Description                                                  |
| ---------- | --------- | ------------------------------------------------------------ |
| expression | `String`  | JSONata expression to evaluate against the input value       |

Table 1: Settings

![Settings panel for the JSONata converter.](./images/converter_jsonata_settings.png)

## Examples

### Extracting a Property

Assuming the input object:

```json
{
  "User": {
    "Name": "Hello World"
  }
}
```

| `expression` | Output          |
| ------------ | --------------- |
| `User.Name`  | `"Hello World"` |

Table 2: Extracting a nested property from a JSON object

### Accepting a JSON String as Input

The converter also accepts the input as a JSON string. For example, with the input:

```json
{
  "Parameters": {
    "NumericValues": [
      [1.1, 2.2],
      [3.3, 4.4]
    ]
  }
}
```

| `expression`                | Output                       |
| --------------------------- | ---------------------------- |
| `Parameters.[NumericValues]` | `[[1.1, 2.2], [3.3, 4.4]]`  |

Table 3: Evaluating an expression against a JSON string input

### Filtering, Aggregating, and Restructuring Arrays

JSONata also supports filtering, aggregation, and restructuring. Assuming the input object:

```json
{
  "Readings": [
    { "Sensor": "Temp", "Value": 21.5, "Unit": "C" },
    { "Sensor": "Temp", "Value": 22.1, "Unit": "C" },
    { "Sensor": "Humidity", "Value": 55, "Unit": "%" }
  ]
}
```

| `expression`                                           | Output                                                                                       | Description                                       |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `Readings[Sensor='Temp'].Value`                        | `[21.5, 22.1]`                                                                               | Filter by sensor and project a single field.      |
| `$sum(Readings.Value)`                                 | `98.6`                                                                                       | Sum every reading value.                          |
| `$count(Readings)`                                     | `3`                                                                                          | Count the items in the array.                     |
| `$average(Readings[Sensor='Temp'].Value)`              | `21.8`                                                                                       | Average values after filtering.                   |
| `Readings.{ "name": Sensor, "value": Value }`          | `[{"name":"Temp","value":21.5}, {"name":"Temp","value":22.1}, {"name":"Humidity","value":55}]` | Restructure each item into a new object shape. |
| `$count(Readings) > 0 ? "ok" : "empty"`                | `"ok"`                                                                                       | Return one of two values based on a condition.    |

Table 4: Filtering, aggregating, and restructuring an array of items

### Invalid Input

This converter fails in any of the cases below. For what happens to the rest of the chain when a converter fails (the error is logged, reported for monitoring, and the next task does not run), see [[user-guide-automation-converters-index]].

| Input               | `expression`           | Result                                                                |
| ------------------- | ---------------------- | --------------------------------------------------------------------- |
| Any value           | *(not set / empty)*    | Fails: an expression must be defined.                                 |
| Any value           | `$sum(example.value]`  | Fails: the expression is not a valid JSONata.                         |
| `"{ \"key\": 123 } invalidData"` | `key`        | Fails: the value cannot be parsed into a JSON object.                 |

Table 5: Inputs and expressions that cause the converter to fail