JMESPath Tutorial¶

Basic Expressions¶

The simplest JMESPath expression is an identifier, which selects a key in an JSON object:

Try changing the expression above to b, and c and note the updated result. Also note that if you refer to a key that does not exist, a value of null (or the language equivalent of null) is returned.

You can use a subexpression to return to nested values in a JSON object:

If you refer to a key that does not exist, a value of null is returned. Attempting to subsequently access identifiers will continue to return a value of null. Try changing the expression to b.c.d.e above.

Index Expressions allow you to select a specific element in a list. It should look similar to array access in common programming languages. Indexing is 0 based.

If you specify an index that’s larger than the list, a value of null is returned. You can also use negative indexing to index from the end of the list. [-1] refers to the last element in the list, [-2] refers to the penultimate element. Try it out in the example above.

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

Slicing¶

Slices allow you to select a contiguous subset of an array. If you’ve ever used slicing in python, then you already know how to use JMESPath slices. In its simplest form, 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. Let’s take a look at some examples. First, given an array of integers from 0 to 9, let’s select the first half of the array:

This slice result contains the elements 0, 1, 2, 3, and 4. The element at index 5 is not included. If we want to select the second half of the array, we can use this expression:

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

Try modifying the example above to only include the last half of the array elements without specifying the end value of 10.

The general form of a slice is [start:stop:step]. So far we’ve looked at the [start:stop] form. By default, the 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.

Also note in this example we’re omitting the start as well as the stop value, which means to use 0 for the start value, and 10 for the stop value. In this example, the expression [::2] is equivalent to [0:10:2].

The last thing to know about slices is that just like indexing a single value, all the values can be negative. If the step value is negative, then the slice is created in reverse order. For example:

The above expression creates a slice but in reverse order.

If you want all the details about how slices work, check out the section in the JMESPath specification.

Projections¶

Projections are one of the key features of JMESPath. It allows you to apply an expression to a collection of elements. There are five kinds of projections:

• List Projections

• Slice Projections

• Object Projections

• Flatten Projections

• Filter Projections

evaluate(ops, inputData) -> [{"numArgs": 2}, {"numArgs": 3},
                             {"variadic": True}]

evaluate(numArgs, {numArgs: 2}) -> 2
evaluate(numArgs, {numArgs: 3}) -> 3
evaluate(numArgs, {variadic: true}) -> null

1st       r0                         r1
2nd i0          i1             i0            i1
[["running", "stopped"], ["terminated", "running"]]

result = []
foreach machine in inputData['machines']
  if machine['state'] == 'running'
    result.insert_at_end(machine['name'])
return result

Pipe Expressions¶

Projections are an important concept in JMESPath. However, there are times when projection semantics are not what you want. A common scenario is when you want to operate of the result of a projection rather than projecting an expression onto each element in the array. For example, the expression people[*].first will give you an array containing the first names of everyone in the people array. What if you wanted the first element in that list? If you tried people[*].first[0] that you just evaluate first[0] for each element in the people array, and because indexing is not defined for strings, the final result would be an empty array, []. To accomplish the desired result, you can use a pipe expression, <expression> | <expression>, to indicate that a projection must stop. This is shown in the example below:

In the example above, the RHS of the list projection is first. When a pipe is encountered, the result up to that point is passed to the RHS of the pipe expression. The pipe expression is evaluated as:

evaluate(people[*].first, inputData) -> ["James", "Jacob", "Jayden"]
evaluate([0], ["James", "Jacob", "Jayden"]) -> "James"

MultiSelect¶

Up to this point, we’ve looked at JMESPath expressions that help to pare down a JSON document into just the elements you’re interested in. This next concept, multiselect lists and multiselect hashes allow you to create JSON elements. This allows you to create elements that don’t exist in a JSON document. A multiselect list creates a list and a multiselect hash creates a JSON object.

This is an example of a multiselect list:

In the expression above, the [name, state.name] portion is a multiselect list. It says to create a list of two element, the first element is the result of evaluating the name expression against the list element, and the second element is the result of evaluating state.name. Each list element will therefore create a two element list, and the final result of the entire expression is a list of two element lists.

Unlike a projection, the result of the expression is always included, even if the result is a null. If you change the above expression to people[].[foo, bar] each two element list will be [null, null].

A multiselect hash has the same basic idea as a multiselect list, except it instead creates a hash instead of an array. Using the same example above, if we instead wanted to create a two element hash that had two keys, Name and State, we could use this:

Functions¶

JMESPath supports function expressions, for example:

Functions can be used to transform and filter data in powerful ways. The full list of functions can be found here, and the function expression spec has the complete details.

Below are a few examples of functions.

This example prints the name of the oldest person in the people array:

Functions can also be combined with filter expressions. In the example below, the JMESPath expressions finds all elements in myarray that contains the string foo.

The @ character in the example above refers to the current element being evaluated in myarray. The expression contains(@, 'foo') will return true if the current element in the myarray array contains the string foo.

While the function expression spec has all the details, there are a few things to keep in mind when working with functions:

• Function arguments have types. If an argument for a function has the wrong type, an invalid-type error will occur. There are functions that can do type conversions (to_string, to_number) to help get arguments converted to their proper type.

• If a function is called with the wrong number of arguments, an invalid-arity will occur.

Next Steps¶

We’ve now seen an overview of the JMESPath language. The next things to do are:

• See the JMESPath Examples. You’ll see common JMESPath expressions that go beyond the tutorial. You’ll also see you how to combine multiple features together in order to best leverage JMESPath expressions.

• To actually start using JMESPath, pick the language of your choice, and check out the JMESPath Libraries page for more information on using JMESPath in the language of your choice.

• Read the JMESPath Spec, which has the official ABNF grammar and full details of the semantics of the language.