JSONata

Apply a JSONata query to select, reshape, and compute values from JSON. Use it when you need more than simple field extraction: filtering, aggregation, mapping, or building a new JSON shape from an existing payload. JSONata lives in the Data format category of the fx menu. For expression syntax and operators, see the JSONata documentation.

Parameters

Parameter	Type	Required	Default	Description
Input	string	yes	—	JSON document as a string. Must parse as JSON.
Query	string	yes	""	JSONata expression to evaluate. See the JSONata documentation for syntax and built-in functions.
Variable Bindings	string	no	—	Variables to bind into the expression, as a JSON object string. Example: {"var1": "value1", "var2": 123}. Referenced in Query as $varName.

Input is the primary JSON document (previous step output or a literal).

Tip

Enable Variable Bindings from + Advanced only when the query needs named variables. Leave it off for simple field selection and most aggregates.

Returned value

Type	Description
string	The expression result. Object and array results are a JSON string. Primitive results (string, number, boolean, null) use their string form (for example 85).

Limitations

• Input, Query, and Variable Bindings (when set) must be strings. Non-string input or query raises an error.
• Input and Variable Bindings must be valid JSON. Empty or malformed JSON raises Invalid JSON format.
• An empty or syntactically invalid Query raises Invalid JSONata expression. See JSONata documentation for valid expression forms.
• Variable Bindings must be a JSON object. A bindings document of null is rejected.
• Large integer values in object results are preserved when the result is stringified (for example, BSON-style IDs).

Caution

Invalid JSON in Input or Variable Bindings, or an invalid Query, stops evaluation with an error — fix the string before re-running the step.

Examples

Select a field

Extract a single property from a JSON object — the most common JSONata use in a flow. Pass the previous step’s JSON into Input, set Query to the field name, and read the string result under Output value.

1. Set Input to the JSON from the previous step (or a literal document).

2. Set Query to the field path. Paste:

   Query

   name

3. Confirm Output value shows the selected field.

   

Aggregate values

Compute a total or other aggregate over an array without leaving Studio. Use JSONata aggregation functions such as $sum on nested fields — see aggregation functions in the JSONata docs.

1. Set Input to a JSON document that contains the array to aggregate.

2. Set Query to the aggregate expression. Paste:

   Query

   $sum(items.(price * quantity))

3. Confirm Output value is the numeric result as a string.

   

Filter with variable bindings

Reuse the same query with different filter values by binding variables instead of hard-coding them in Query. Use this when the city (or other filter) comes from another step or should change without editing the expression. Bound names are referenced as $name in the query — see programming constructs in the JSONata docs.

1. Open + Advanced and enable Variable Bindings.

   

2. Set Input to the JSON document. Set Query to a filter that uses $city. Paste:

   Query

   persons[city=$city].name

3. Set Variable Bindings to a JSON object that defines city. Paste:

   Variable Bindings

   {"city":"Paris"}

4. Confirm Output value lists the matching names as a JSON string.