JSONata is a JSON (JavaScript Object Notation) 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.

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

You can use the . operator to access nested properties.

body.temp

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
}

3) Add new fields

Building on the previous example, sometimes you want to create your 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"
}

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 to 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
  }
}

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]
  }
}

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()
}

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)
}

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
}

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)
  }
)

See JSONata’s function documentation for more information.

9) Sorting and filtering 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)
}

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']
}

10) Extensions to JSONata

In case all of these examples weren’t enough, JSONata also includes a series of extension APIs.

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.

• Data Analytics

• Work
• Coder
• Data Analytics