Find a certified Blues partner to help accelerate your product on the new Partner Catalog

JSONata is a JSON query and transformation language. JSONata can do a lot, which can make it intimidating to start with. This guide aims to make JSONata easier to use by providing concrete examples of the language in action.

This guide’s examples all take the same input JSON (shown below), and use JSONata to query or transform that input in interesting ways.

Input JSON

{
  "device": "dev:5c0272356817",
  "when": 1643398446,
  "body": {
    "humid": 56.23,
    "temp": 35.52
  },
  "best_location_type": "triangulated",
  "tower_country": "US",
  "tower_lat": 44.9288392,
  "tower_lon": -84.9283943,
  "tower_location": "Grand Ledge, MI",
  "tower_id": "310,410,25878,88213007",
  "tri_country": "US",
  "tri_lat": 44.76386883,
  "tri_lon": -83.64839822,
  "tri_location": "Lansing, MI",
  "settings": [
    { "name": "power_saving", "value": false },
    { "name": "detect_motion", "value": true },
    { "name": "sample_interval", "value": 5 }
  ]
}

All screenshots in this guide come from JSONata Exerciser—a handy site for testing JSONata in your web browser. To use the JSONata Exerciser you must place your input JSON in the left pane and your JSONata in the top-right pane. The Exerciser automatically applies the JSONata to the input JSON, and displays the result in the bottom-right pane.

The JSONata explorer
1) Grab one piece of data

Let’s start simple. Sometimes all you want to do is grab one piece of data out of a JSON object. With JSONata you can do that by referencing the appropriate property name.

device

Using JSONata to get one piece of data
You can use the . operator to access nested properties.

body.temp

Using JSONata to get nested data
2) Create a smaller JSON object

JSONata allows you to take a large JSON input, and output a separate JSON object that only contains the properties you need. For example, the following JSONata returns a JSON object that only contains the device property (and its value).

{
  "device": device
}

Using JSONata to create a smaller JSON object
3) Add new fields

Building on the previous example, sometimes you want to create your own JSON structure that includes a mix of data from your input JSON, and completely new properties. The following JSONata outputs a device property from the input JSON, and a newly created property and value.

{
  "device": device,
  "a_new_property": "a value"
}

Using JSONata to create a new JSON structure

4) Create a new JSON structure altogether

You can use JSONata to create a JSON object that uses a completely different structure than your input JSON. This can be useful if, for instance, you need send JSON to a system that expects JSON data in a completely different format.

The JSONata below creates a JSON object with a new data property that includes two properties from the input JSON.

{
  "data": {
    "device": device,
    "when": when
  }
}

Using JSONata to create a new JSON structure

5) Using built-in functions

JSONata has several built-in functions that can help you parse data. The example below uses JSONata’s $split function to break "tower_id": "310,410,25878,88213007" into four properties in a new JSON object.

{
  "tower": {
    "mobile_country_code": $split(tower_id,",")[0],
    "mobile_network_code": $split(tower_id,",")[1],
    "location_area_code": $split(tower_id,",")[2],
    "cell_id": $split(tower_id,",")[3]
  }
}

Using JSONata built-in functions
There are dozens of other built-in functions you might want to experiment with, including $trim() and $substring() for working with strings, or $round(), $floor(), and $ceil() for working with numbers.

6) Working with dates and times

JSONata has several features that help with date/time processing. Perhaps the most useful of these is $now(), which provides an easy way to add a timestamp to your JSON output.

{
  "timestamp": $now()
}

Using JSONata to get the current date
You might also find $fromMillis() useful, as it allows you to convert a millisecond-based time to a formatted string representation.

{
  "time": $fromMillis(when * 1000)
}

Using JSONata to convert dates to strings

You can control the format of the $fromMillis() output with its optional picture argument. See the $fromMillis() documentation for more information.

7) Adding conditional logic

JSONata allows you to perform conditional checks using the ternary operator. For example, the JSONata below selects either tri_location or tower_location depending on the value of best_location_type.

{
  "location": best_location_type = "triangulated" ? tri_location : tower_location
}

Using conditional logic in JSONata
8) Creating functions

If your logic is more advanced you can create reusable functions directly in JSONata.

Functions have a few additional rules to follow, such as needing to introduce a scope using parenthesis. This is a bit easier to understand with an example, so check out the code below, which defines a custom $localizeTemperature function, and uses it to convert temperature values to Fahrenheit or Celsius depending on the country.

(
  $localizeTemperature := function($degrees_celsius, $country) {(
    $conversion_ratio := (9 / 5);
    ($country = "US")
      ? (($degrees_celsius * $conversion_ratio) + 32)
      : $degrees_celsius;
  )};
  {
    "temp": $localizeTemperature(body.temp, best_country)
  }
)

Creating functions in JSONata
See JSONata’s function documentation for more information.

9) Sorting and filter data

JSONata provides an order-by operator that allows you to sort an array of JSON data. For example, the code below sorts the settings array by its name property.

{
  "settings": settings^(name)
}

Using JSONata to sort data
The filter operator allows you to select items in an array that match a provided condition. For example, the code below selects all objects in settings that have a name of "power_saving".

{
  "settings": settings[name = 'power_saving']
}

Using JSONata to filter data
10) Blues extensions to JSONata

In case all of these examples weren’t enough, JSONata also includes a series of extension APIs. Here at Blues we use JSONata a lot, as we find it a handy way to manipulate JSON before routing data to cloud services, so we’ve extended the language with a few new features.

For instance, we allow our users to refer to environment variables using the $ operator. As an example, the JSONata code below uses $interval to read an environment variable named interval.

{
  "interval": $interval
}

We also offer a custom function named $doNotRoute() that allows you to conditionally route your data to a service. For example, the code below only routes data if a location exists.

($result := ($exists(location)) ? $result : $doNotRoute();)

Wrapping up

Hopefully you’ve found these examples useful as you’re trying to learn JSONata. For more, check out JSONata’s extensive documentation site.

Share on: