10 Examples to Help You Learn JSONata

Blues Wireless
jsonata examples
Illustration: © IoT For All

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.

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 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 add new fields

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

Author
Blues Wireless
Blues Wireless
We provide cellular that works, so you can build IoT products that change the world. No activation or deactivation charges. No monthly data charges. No monthly device charges.
We provide cellular that works, so you can build IoT products that change the world. No activation or deactivation charges. No monthly data charges. No monthly device charges.