Understand and use JSONata

JSONata is a lightweight query and transformation language for working with JSON data. In Applaud, you can use JSONata expressions to find values in data, transform data into a different structure, and perform calculations or conditional logic.

JSONata is especially useful when you need to work with data returned by a tool or action in an agentic workflow.

What is JSONata?

JSONata lets you describe what you want to do with JSON data using a compact expression.

For example, suppose an action returns this data:

{
 "employee": {
   "firstName": "Alex",
   "lastName": "Morgan"
 }
}

You can use the following JSONata expression to return the employee's first name:

employee.firstName

The result is:

Alex

You can also combine values. For example:

employee.firstName & " " & employee.lastName

This returns:

Alex Morgan

JSONata can do more than retrieve individual values. You can use it to filter lists, transform objects, perform calculations, and apply conditional logic.

When to use JSONata

Use JSONata when you need to manipulate or extract data that is available as JSON.

Common uses include:

• Extracting a specific value from an action result
• Combining multiple values into a single value
• Filtering a list of objects
• Transforming data into a different structure
• Performing calculations
• Checking whether a value meets a condition
• Creating a value from several pieces of workflow data

For example, you might use JSONata to extract the email address from a person record before passing it to another action.

How JSONata works

A JSONata expression operates on an input JSON object.

Consider this example:

{
 "person": {
   "name": "Alex Morgan",
   "department": "HR",
   "location": "London"
 }
}

To access the person's department, use:

person.department

To access the person's location, use:

person.location

JSONata follows the structure of the JSON data. Use a period (.) to move between nested properties.

Access a nested value

For this data:

{
 "employee": {
   "contact": {
     "email": "alex@example.com"
   }
 }
}

Use:

employee.contact.email

The result is:

alex@example.com

Combine values

Use the & operator to combine strings.

employee.firstName & " " & employee.lastName

You can also include text directly in the expression:

"Employee: " & employee.firstName

Work with arrays

JSON data often contains arrays, or lists of values.

For example:

{
 "employees": [
   {
     "name": "Alex",
     "department": "HR"
   },
   {
     "name": "Sam",
     "department": "Finance"
   },
   {
     "name": "Jordan",
     "department": "HR"
   }
 ]
}

To return all employee names, use:

employees.name

This returns:

[
 "Alex",
 "Sam",
 "Jordan"
]

Filter data

You can filter an array using a condition inside square brackets.

For example:

employees[department = "HR"]

This returns the employees whose department is HR.

You can then return just their names:

employees[department = "HR"].name

The result is:

[
 "Alex",
 "Jordan"
]

Use JSONata in a workflow

JSONata is particularly useful when one workflow action produces data that another action needs in a different format.

For example, imagine a workflow that:

1. Gets a person's details.
2. Uses those details to create a case.
3. Needs the person's email address as an input to the next action.

If the first action returns:

{
 "person": {
   "name": "Alex Morgan",
   "email": "alex@example.com",
   "department": "HR"
 }
}

You can use:

person.email

to extract the email address.

You can then use the resulting value as an input for the next action.

Use workflow variables

When working in a workflow, the data you need might be stored in a workflow variable rather than directly in the action result.

Use the @ variable picker to insert the relevant workflow variable into the expression, then use JSONata to access or transform the data it contains.

For example, if a variable contains an employee object, you might use an expression such as:

employee.email

The exact variables and data structures available depend on the action and workflow you are building.

Perform calculations

JSONata supports mathematical expressions.

For example:

price * quantity

If price is 25 and quantity is 4, the result is:

100

You can use standard mathematical operators such as:

You can also use comparison operators when you need to evaluate a value.

For example:

amount > 100

This returns true when amount is greater than 100.

Use conditional expressions

JSONata supports conditional expressions that let you return different values depending on a condition.

For example:

amount > 100 ? "High" : "Standard"

If amount is greater than 100, the expression returns:

High

Otherwise, it returns:

Standard

This can be useful when preparing data for another workflow action or deciding which value to pass to an action.

Use JSONata functions

JSONata includes functions for common operations such as working with strings, numbers, arrays, and dates.

For example, you can use $uppercase() to convert text to uppercase:

$uppercase(name)

You can use $lowercase() to convert text to lowercase:

$lowercase(name)

You can use $count() to count items in an array:

$count(employees)

You can combine functions with other expressions. For example:

$uppercase(firstName) & " " & $uppercase(lastName)

Transform JSON data

One of the most useful features of JSONata is its ability to create a new JSON structure from existing data.

For example, given:

{
 "firstName": "Alex",
 "lastName": "Morgan",
 "email": "alex@example.com"
}

You can create a new object:

{
 "fullName": firstName & " " & lastName,
 "emailAddress": email
}

The result is:

{
 "fullName": "Alex Morgan",
 "emailAddress": "alex@example.com"
}

This is useful when the output from one action does not match the input expected by another action.

Common JSONata patterns

The following patterns cover many common use cases.

Tips for writing JSONata expressions

Keep your expressions as simple as possible. A short expression is easier to understand, test, and maintain.

Start with the data structure

Before writing an expression, look at the JSON data you are working with. Identify:

• The property you need
• Whether the property is nested
• Whether the data is an object or an array
• Whether the value can be empty or missing

For example, if the value is nested under person.contact.email, using person.email will not return the expected result.

Test expressions with real data

Use representative data when testing an expression. A value that works with one response might behave differently when a property is missing or an array contains multiple items.

Consider empty or missing values

Not every response contains every property. Make sure your expression handles the data your workflow can actually receive.

Keep transformations close to where they are needed

If an action returns a value in a format that the next action cannot use, JSONata can often transform the value between the two actions rather than requiring an additional workflow step.

Troubleshoot JSONata expressions

If an expression does not return the expected result, check the following:

The property path is incorrect

Check the structure of the input JSON and make sure each property name is spelled correctly.

The value is nested

Make sure your expression follows the complete path to the value.

For example:

person.contact.email

rather than:

person.email

The data is an array

If the value occurs inside a list, you might need to select or filter the relevant item first.

The property does not exist

Check whether the action always returns the property. A missing property can result in an empty or unexpected value.

The expression returns multiple values

Check whether your expression is selecting a single value or a list. This matters when the next workflow action expects a single value.

The data type is different from what you expected

A value might be a string, number, Boolean, object, or array. Check the input data before deciding how to manipulate it.

JSONata and JSON are not the same thing

JSON and JSONata serve different purposes.

• JSON is a data format. It describes data using objects, arrays, properties, and values.
• JSONata is an expression language. It lets you query, calculate, filter, and transform JSON data.

For example, this is JSON:

{
 "name": "Alex",
 "department": "HR"
}

This is JSONata:

name

The JSON contains the data. The JSONata expression tells Applaud which part of that data to use.

Learn more

For the full JSONata language reference, including operators, functions, expressions, and transformation syntax, see the JSONata documentation.