JSONata functions

JSONata functions overview

JSONata functions let you run a JSONata query directly on data being pulled into a workflow step.

JSONata functions use version 1.8.6, the same version as the JSON Transformer connector. See the JSONata documentation for the full language reference.

Tray's 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 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.

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:

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

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

{
  "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.

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.

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.

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 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 - a sandbox for building and testing queries before moving them into your workflow
• docs.jsonata.org - the full JSONata language reference
• JSONata versions - which version the documentation currently covers