# JSONata functions

Use JSONata expressions directly in step input fields to transform data without adding a workflow step

## JSONata functions overview

JSONata functions let you run a [JSONata](https://jsonata.org/) query directly on data being pulled into a workflow step.

JSONata functions use version 1.8.6, the same version as the [JSON Transformer](https://tray.ai/documentation/connectors/core/json-transformer) connector. See the [JSONata documentation](https://docs.jsonata.org/overview) for the full language reference.

Tray's [inline functions](https://tray.ai/documentation/platform/automation-integration/building-workflows/mapping-data/inline-functions) already cover common transformations such as formatting a date or trimming a string.
JSONata handles the more advanced shaping that would otherwise need a dedicated [JSON Transformer](https://tray.ai/documentation/connectors/core/json-transformer) step: restructuring objects, filtering and grouping arrays, and running calculations across a payload.
A JSONata function can also return an array or an object, where inline functions are limited to string, number and boolean values.

Doing this inline rather than in a separate step means:

* Fewer steps in your workflow.
* Lower task usage.
* Less complexity for you to work with.

> **Info:** JSONata functions are aimed at users who are already comfortable with the JSONata query language.
> For simpler transformations, [inline functions](https://tray.ai/documentation/platform/automation-integration/building-workflows/mapping-data/inline-functions) are usually the better choice.

### Where you can use JSONata functions

JSONata functions are available anywhere inline functions are supported.

In the connector properties panel, select `jsonata` from the input type drop-down for the field you want to transform:

![jsonata-select-type-dropdown](https://tray.ai/documentation/images/platform/automation-integration/building-workflows/mapping-data/jsonata-functions/jsonata-select-type-dropdown.png)

The types offered in this drop-down depend on the field you are working in, so `jsonata` appears alongside whichever other types that field accepts.

### The JSONata editor

Selecting `jsonata` splits the field into two parts in the properties panel:

* **JSON data** - the JSON object or array to transform. Map data into this field as you would any other, using data from previous steps or a project config variable
* **Query** - the JSONata expression used to transform that data

![jsonata-properties-panel](https://tray.ai/documentation/images/platform/automation-integration/building-workflows/mapping-data/jsonata-functions/jsonata-properties-panel.png)

In the example above, the **JSON data** field is mapped to a project config variable called `orderData`, which holds the following order:

```json
{
  "order_id": "SO-4471",
  "customer": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com"
  },
  "lines": [
    { "sku": "TRAY-100", "qty": 2, "unit_price": 49.5 },
    { "sku": "TRAY-250", "qty": 1, "unit_price": 120 },
    { "sku": "TRAY-010", "qty": 4, "unit_price": 9.75 }
  ]
}
```

The **Query** field shows a preview of your expression, truncated to fit the panel.
Click it to open the **Edit JSONata Query** modal, where you can see the full expression and edit it in a code editor with JSONata syntax highlighting and line numbers.
The editor and the modal are both resizable, so you can work comfortably with longer, multi-line expressions.

![jsonata-edit-query-modal](https://tray.ai/documentation/images/platform/automation-integration/building-workflows/mapping-data/jsonata-functions/jsonata-edit-query-modal.png)

The query shown here reshapes each line item in the order into a new object:

```
lines.{'product': sku, 'quantity': qty, 'total': qty * unit_price}
```

Select **Save** to apply your changes.

### Return type

JSONata functions support the following return types:

* string
* number
* boolean
* array
* object

The return type is set using the Return type selector at the bottom of the **Edit JSONata Query** modal, in the same way as for [inline functions](https://tray.ai/documentation/platform/automation-integration/building-workflows/mapping-data/inline-functions#return-type).

Selecting the appropriate return type ensures values are passed to downstream steps in the expected format.
JSONata expressions return non-string values far more often than inline functions do, so it is worth checking this setting whenever your query returns anything other than a string.

> **Info:** As with inline functions, the return types available to you are restricted by the input schema of the field you are working in.
> A field that only accepts a string will not offer `array` or `object` as a return type.
> See [Satisfying input schema](https://tray.ai/documentation/platform/automation-integration/building-workflows/mapping-data/input-schema) for more on how schemas constrain what a field will accept.

### Validating your query

Your query is checked for syntax errors when you click away from the Query field, and any error is shown in the editor.

If a stored value cannot be read, the editor shows the raw value as read-only instead of splitting it into the two fields. This is deliberate: it prevents the editor from overwriting a value it cannot safely interpret. Correct the raw value to restore normal editing.

### Learning JSONata

This page covers the JSONata function itself, not the JSONata query language.

For an introduction to the language, with worked examples using data of the kind you will see in Tray, see the [JSON Transformer](https://tray.ai/documentation/connectors/core/json-transformer) documentation. It covers extracting data, structuring output, operators, functions, chaining with `~>`, variables, and defining your own functions.

These resources are worth having open while you work:

* [try.jsonata.org](https://try.jsonata.org) - a sandbox for building and testing queries before moving them into your workflow
* [docs.jsonata.org](https://docs.jsonata.org) - the full JSONata language reference
* [JSONata versions](https://docs.jsonata.org/versions) - which version the documentation currently covers

> **Info:** When testing in the sandbox, copy the output data log of the step containing the JSON you want to work with.
> Tray log data can vary from what you would get in other tools, usually by adding a key of `data` or `result` at the top level of the object.