Wednesday, July 12, 2017


What is JMESPath ?

JMESPath is a query language for JSON. You can extract and transform elements from a JSON document.

Why JMESPath ?

Web developers deal with JSON a lot. It may be a javascript client or a client that consumes and API. This is an useful tool to have in your troubleshooting toolbox. You will be able to search a JSON document quickly. You can also chain the queries by using the pipe operator to create your desired JSON output. This is more powerful than the simple search capability found in your favorite editor or IDE. Let's go through some of the basics by working through the tutorial found on the JMESPath home page.

Basic Expressions

Let's look at the simplest JMESPath expression, an identifier. An identifier selects a the value for a given key in a JSON object.

Demo 1 with Custom Voice Over

Let's now see how to use a subexpression to return the nested values in a JSON object.

Demo 2 with Custom Voice Over

Let's now look at index expressions. Index expressions allow you to select a specific element in  list. It is similar to array access in common programming languages. Indexing is 0 based.

Demo 3 with Custom Voice Over

You can combine identifiers, sub expressions and index expressions to access JSON elements.

Demo 4

Let's now look at slicing. Slicing allows you to select a contiguous subset of an array. You can specify the starting index and the ending index. The ending index is the first index which you do not want included in the slice. Given an array of integers from 0 to 9, let's select the first half of the array:

Demo 5

This slice result contains the elements 0, 1, 2, 3 and 4. The element at index 5 is not included.

Demo 6

If we want to select the second half of the array, we can use the expression: [5:10]

The above two examples can be shortened. If the start or step value is omitted, it is assumed to be the start of the end of the array. For example:

Demo 7

The general form of a slice is start:stop:step. So far, we've looked at the start:stop form. By default, teh step value is 1, which means to include every element in the range specified by the start and stop value. However, we can use the step value to skip over elements. For example, to select only the even elements from the array.

Demo 8

In this example we are omitting the start and the stop value. So, the start value defaults to 0 and the stop value defaults to 10. In this example ::2 is equivalent to 0:10:2

If the indexing is negative, then the slice is created in reverse order.

Let's now look at projections. A wildcard expression creates a list projection, which is a projection over a JSON array. In this example, we have a JSON document that describes people, and each array element is a JSON object that has a first, last and age key. We can list all the first names in our list using this expression:

Demo 9

If you want to learn more, check out the tutorials section of JMESPath home page. In a real project, you need a command line utility for JMESPath. Let's install the JMESPath Terminal on play with JSON documents from a terminal session. We can install it using pip.

To use JMESPath in your projects, you can use the jmespath gem. The first parameter is the query and the second parameter is the JSON. It also has indifferent access. It also allows you to query JSON documents in your file system.