JMESPath Specification¶

Examples¶

search(foo, {"foo": "value"}) -> "value"
search(bar, {"foo": "value"}) -> null
search(foo, {"foo": [0, 1, 2]}) -> [0, 1, 2]
search("with space", {"with space": "value"}) -> "value"
search("special chars: !@#", {"special chars: !@#": "value"}) -> "value"
search("quote\"char", {"quote\"char": "value"}) -> "value"
search("\u2713", {"\u2713": "value"}) -> "value"

Examples¶

Given a JSON document: {"foo": {"bar": "baz"}}, and a jmespath expression: foo.bar, the evaluation process would be:

left-evaluation = search("foo", {"foo": {"bar": "baz"}}) -> {"bar": "baz"}
result = search("bar": {"bar": "baz"}) -> "baz"

The final result in this example is "baz".

Additional examples:

search(foo.bar, {"foo": {"bar": "value"}}) -> "value"
search(foo."bar", {"foo": {"bar": "value"}}) -> "value"
search(foo.bar, {"foo": {"baz": "value"}}) -> null
search(foo.bar.baz, {"foo": {"bar": {"baz": "value"}}}) -> "value"

Slices¶

slice-expression  = [number] ":" [number] [ ":" [number] ]

A slice expression allows you to select a contiguous subset of an array. A slice has a start, stop, and step value. The general form of a slice is [start:stop:step], but each component is optional and can be omitted.

Given a start, stop, and step value, the sub elements in an array are extracted as follows:

• The first element in the extracted array is the index denoted by start.

• The last element in the extracted array is the index denoted by end - 1.

• The step value determines how many indices to skip after each element is selected from the array. An array of 1 (the default step) will not skip any indices. A step value of 2 will skip every other index while extracting elements from an array. A step value of -1 will extract values in reverse order from the array.

Slice expressions adhere to the following rules:

• If a negative start position is given, it is calculated as the total length of the array plus the given start position.

• If no start position is given, it is assumed to be 0 if the given step is greater than 0 or the end of the array if the given step is less than 0.

• If a negative stop position is given, it is calculated as the total length of the array plus the given stop position.

• If no stop position is given, it is assumed to be the length of the array if the given step is greater than 0 or 0 if the given step is less than 0.

• If the given step is omitted, it it assumed to be 1.

• If the given step is 0, an invalid-value error MUST be raised.

• If the element being sliced is not an array, the result is null.

• If the element being sliced is an array and yields no results, the result MUST be an empty array.

Examples¶

search([0:4:1], [0, 1, 2, 3]) -> [0, 1, 2, 3]
search([0:4], [0, 1, 2, 3]) -> [0, 1, 2, 3]
search([0:3], [0, 1, 2, 3]) -> [0, 1, 2]
search([:2], [0, 1, 2, 3]) -> [0, 1]
search([::2], [0, 1, 2, 3]) -> [0, 2]
search([::-1], [0, 1, 2, 3]) -> [3, 2, 1, 0]
search([-2:], [0, 1, 2, 3]) -> [2, 3]

Flatten Operator¶

When the character sequence [] is provided as a bracket specifier, then a flattening operation occurs on the current result. The flattening operator will merge sublists in the current result into a single list. The flattening operator has the following semantics:

• Create an empty result list.

• Iterate over the elements of the current result.

• If the current element is not a list, add to the end of the result list.

• If the current element is a list, add each element of the current element to the end of the result list.

• The result list is now the new current result.

Once the flattening operation has been performed, subsequent operations are projected onto the flattened list with the same semantics as a wildcard expression. Thus the difference between [*] and [] is that [] will first flatten sublists in the current result.

Examples¶

search([0], ["first", "second", "third"]) -> "first"
search([-1], ["first", "second", "third"]) -> "third"
search([100], ["first", "second", "third"]) -> null
search(foo[0], {"foo": ["first", "second", "third"]) -> "first"
search(foo[100], {"foo": ["first", "second", "third"]) -> null
search(foo[0][0], {"foo": [[0, 1], [1, 2]]}) -> 0

Examples¶

search(foo || bar, {"foo": "foo-value"}) -> "foo-value"
search(foo || bar, {"bar": "bar-value"}) -> "bar-value"
search(foo || bar, {"foo": "foo-value", "bar": "bar-value"}) -> "foo-value"
search(foo || bar, {"baz": "baz-value"}) -> null
search(foo || bar || baz, {"baz": "baz-value"}) -> "baz-value"
search(override || mylist[-1], {"mylist": ["one", "two"]}) -> "two"
search(override || mylist[-1], {"mylist": ["one", "two"], "override": "yes"}) -> "yes"

Examples¶

search(True && False, {"True": true, "False": false}) -> false
search(Number && EmptyList, {"Number": 5, EmptyList: []}) -> []
search(foo[?a == `1` && b == `2`],
       {"foo": [{"a": 1, "b": 2}, {"a": 1, "b": 3}]}) -> [{"a": 1, "b": 2}]

Examples¶

search(foo[?(a == `1` || b ==`2`) && c == `5`],
       {"foo": [{"a": 1, "b": 2, "c": 3}, {"a": 3, "b": 4}]}) -> []

Examples¶

search(!True, {"True": true}) -> false
search(!False, {"False": false}) -> true
search(!Number, {"Number": 5}) -> false
search(!EmptyList, {"EmptyList": []}) -> true

Examples¶

search([foo,bar], {"foo": "a", "bar": "b", "baz": "c"}) -> ["a", "b"]
search([foo,bar[0]], {"foo": "a", "bar": ["b"], "baz": "c"}) -> ["a", "b"]
search([foo,bar.baz], {"foo": "a", "bar": {"baz": "b"}}) -> ["a", "b"]
search([foo,baz], {"foo": "a", "bar": "b"}) -> ["a", null]

Examples¶

Given a multi-select-hash expression {foo: one.two, bar: bar} and the data {"bar": "bar", {"one": {"two": "one-two"}}}, the expression is evaluated as follows:

1. A hash is created: {}

2. A key foo is created whose value is the result of evaluating one.two against the provided JSON document: {"foo": evaluate(one.two, <data>)}

3. A key bar is created whose value is the result of evaluting the expression bar against the provided JSON document.

The final result will be: {"foo": "one-two", "bar": "bar"}.

Additional examples:

search({foo: foo, bar: bar}, {"foo": "a", "bar": "b", "baz": "c"})
              -> {"foo": "a", "bar": "b"}
search({foo: foo, firstbar: bar[0]}, {"foo": "a", "bar": ["b"]})
              -> {"foo": "a", "firstbar": "b"}
search({foo: foo, "bar.baz": bar.baz}, {"foo": "a", "bar": {"baz": "b"}})
              -> {"foo": "a", "bar.baz": "b"}
search({foo: foo, baz: baz}, {"foo": "a", "bar": "b"})
              -> {"foo": "a", "baz": null}

Examples¶

search([*].foo, [{"foo": 1}, {"foo": 2}, {"foo": 3}]) -> [1, 2, 3]
search([*].foo, [{"foo": 1}, {"foo": 2}, {"bar": 3}]) -> [1, 2]
search('*.foo', {"a": {"foo": 1}, "b": {"foo": 2}, "c": {"bar": 1}}) -> [1, 2]

Examples¶

search(`"foo"`, "anything") -> "foo"
search(`"foo\`bar"`, "anything") -> "foo`bar"
search(`[1, 2]`, "anything") -> [1, 2]
search(`true`, "anything") -> true
search(`{"a": "b"}`.a, "anything") -> "b"
search({first: a, type: `"mytype"`}, {"a": "b", "c": "d"}) -> {"first": "b", "type": "mytype"}

Comparison Operators¶

The following operations are supported:

• ==, tests for equality.

• !=, tests for inequality.

• <, less than.

• <=, less than or equal to.

• >, greater than.

• >=, greater than or equal to.

The behavior of each operation is dependent on the type of each evaluated expression.

The comparison semantics for each operator are defined below based on the corresponding JSON type:

search('foo[?a<b]', {"foo": [{"a": "char", "b": "char"},
                             {"a": 2, "b": 1},
                             {"a": 1, "b": 2}]})

Examples¶

search(foo[?bar==`10`], {"foo": [{"bar": 1}, {"bar": 10}]}) -> [{"bar": 10}]
search([?bar==`10`], [{"bar": 1}, {"bar": 10}]}) -> [{"bar": 10}]
search(foo[?a==b], {"foo": [{"a": 1, "b": 2}, {"a": 2, "b": 2}]}) -> [{"a": 2, "b": 2}]

Data Types¶

In order to support functions, a type system is needed. The JSON types are used:

• number (integers and double-precision floating-point format in JSON)

• string

• boolean (true or false)

• array (an ordered, sequence of values)

• object (an unordered collection of key value pairs)

• null

There is also an additional type that is not a JSON type that’s used in JMESPath functions:

• expression (denoted by &expression)

current-node¶

The current-node token can be used to represent the current node being evaluated. The current-node token is useful for functions that require the current node being evaluated as an argument. For example, the following expression creates an array containing the total number of elements in the foo object followed by the value of foo["bar"].

foo[].[length(@), bar]

JMESPath assumes that all function arguments operate on the current node unless the argument is a literal or number token. Because of this, an expression such as @.bar would be equivalent to just bar, so the current node is only allowed as a bare expression.

Function Evaluation¶

Functions are evaluated in applicative order. Each argument must be an expression, each argument expression must be evaluated before evaluating the function. The function is then called with the evaluated function arguments. The result of the function-expression is the result returned by the function call. If a function-expression is evaluated for a function that does not exist, the JMESPath implementation must indicate to the caller that an unknown-function error occurred. How and when this error is raised is implementation specific, but implementations should indicate to the caller that this specific error occurred.

Functions can either have a specific arity or be variadic with a minimum number of arguments. If a function-expression is encountered where the arity does not match or the minimum number of arguments for a variadic function is not provided, then implementations must indicate to the caller than an invalid-arity error occurred. How and when this error is raised is implementation specific.

Each function signature declares the types of its input parameters. If any type constraints are not met, implementations must indicate that an invalid-type error occurred.

In order to accommodate type contraints, functions are provided to convert types to other types (to_string, to_number) which are defined below. No explicit type conversion happens unless a user specifically uses one of these type conversion functions.

Function expressions are also allowed as the child element of a sub expression. This allows functions to be used with projections, which can enable functions to be applied to every element in a projection. For example, given the input data of ["1", "2", "3", "notanumber", true], the following expression can be used to convert (and filter) all elements to numbers:

search([].to_number(@), `["1", "2", "3", "notanumber", true]`) -> [1, 2, 3]

This provides a simple mechanism to explicitly convert types when needed.

abs¶

number abs(number $value)

Returns the absolute value of the provided argument. The signature indicates that a number is returned, and that the input argument $value must resolve to a number, otherwise a invalid-type error is triggered.

Below is a worked example. Given:

{"foo": -1, "bar": "2"}

Evaluating abs(foo) works as follows:

1. Evaluate the input argument against the current data:

   search(foo, {"foo": -1, "bar": "2"}) -> -1
   

2. Validate the type of the resolved argument. In this case -1 is of type number so it passes the type check.

3. Call the function with the resolved argument:

   abs(-1) -> 1
   

4. The value of 1 is the resolved value of the function expression abs(foo).

Below is the same steps for evaluating abs(bar):

1. Evaluate the input argument against the current data:

   search(bar, {"foo": -1, "bar": "2"}) -> "2"
   

2. Validate the type of the resolved argument. In this case "2" is of type string so we immediately indicate that an invalid-type error occurred.

As a final example, here is the steps for evaluating abs(to_number(bar)):

1. Evaluate the input argument against the current data:

   search(to_number(bar), {"foo": -1, "bar": "2"})
   

2. In order to evaluate the above expression, we need to evaluate to_number(bar):

   search(bar, {"foo": -1, "bar": "2"}) -> "2"
   # Validate "2" passes the type check for to_number, which it does.
   to_number("2") -> 2
   

   Note that to_number is defined below.

3. Now we can evaluate the original expression:

   search(to_number(bar), {"foo": -1, "bar": "2"}) -> 2
   

4. Call the function with the final resolved value:

   abs(2) -> 2
   

5. The value of 2 is the resolved value of the function expression abs(to_number(bar)).

avg¶

number avg(array[number] $elements)

Returns the average of the elements in the provided array.

An empty array will produce a return value of null.

contains¶

boolean contains(array|string $subject, any $search)

Returns true if the given $subject contains the provided $search string.

If $subject is an array, this function returns true if one of the elements in the array is equal to the provided $search value.

If the provided $subject is a string, this function returns true if the string contains the provided $search argument.

ceil¶

number ceil(number $value)

Returns the next highest integer value by rounding up if necessary.

ends_with¶

boolean ends_with(string $subject, string $prefix)

Returns true if the $subject ends with the $prefix, otherwise this function returns false.

floor¶

number floor(number $value)

Returns the next lowest integer value by rounding down if necessary.

join¶

string join(string $glue, array[string] $stringsarray)

Returns all of the elements from the provided $stringsarray array joined together using the $glue argument as a separator between each.

keys¶

array keys(object $obj)

Returns an array containing the keys of the provided object. Note that because JSON hashes are inheritently unordered, the keys associated with the provided object obj are inheritently unordered. Implementations are not required to return keys in any specific order.

length¶

number length(string|array|object $subject)

Returns the length of the given argument using the following types rules:

1. string: returns the number of code points in the string

2. array: returns the number of elements in the array

3. object: returns the number of key-value pairs in the object

map¶

array[any] map(expression->any->any expr, array[any] elements)

Apply the expr to every element in the elements array and return the array of results. An elements of length N will produce a return array of length N.

Unlike a projection, ([*].bar), map() will include the result of applying the expr for every element in the elements array, even if the result if null.

max¶

number max(array[number]|array[string] $collection)

Returns the highest found number in the provided array argument.

An empty array will produce a return value of null.

max_by¶

max_by(array elements, expression->number|expression->string expr)

Return the maximum element in an array using the expression expr as the comparison key. The entire maximum element is returned. Below are several examples using the people array (defined above) as the given input.

merge¶

object merge([object *argument, [, object $...]])

Accepts 0 or more objects as arguments, and returns a single object with subsequent objects merged. Each subsequent object’s key/value pairs are added to the preceding object. This function is used to combine multiple objects into one. You can think of this as the first object being the base object, and each subsequent argument being overrides that are applied to the base object.

min¶

number min(array[number]|array[string] $collection)

Returns the lowest found number in the provided $collection argument.

min_by¶

min_by(array elements, expression->number|expression->string expr)

Return the minimum element in an array using the expression expr as the comparison key. The entire maximum element is returned. Below are several examples using the people array (defined above) as the given input.

not_null¶

any not_null([any $argument [, any $...]])

Returns the first argument that does not resolve to null. This function accepts one or more arguments, and will evaluate them in order until a non null argument is encounted. If all arguments values resolve to null, then a value of null is returned.

reverse¶

array reverse(string|array $argument)

Reverses the order of the $argument.

sort¶

array sort(array[number]|array[string] $list)

This function accepts an array $list argument and returns the sorted elements of the $list as an array.

The array must be a list of strings or numbers. Sorting strings is based on code points. Locale is not taken into account.

sort_by¶

sort_by(array elements, expression->number|expression->string expr)

Sort an array using an expression expr as the sort key. For each element in the array of elements, the expr expression is applied and the resulting value is used as the key used when sorting the elements.

If the result of evaluating the expr against the current array element results in type other than a number or a string, an invalid-type error will occur.

Below are several examples using the people array (defined above) as the given input. sort_by follows the same sorting logic as the sort function.

starts_with¶

boolean starts_with(string $subject, string $prefix)

Returns true if the $subject starts with the $prefix, otherwise this function returns false.

sum¶

number sum(array[number] $collection)

Returns the sum of the provided array argument.

An empty array will produce a return value of 0.

to_array¶

array to_array(any $arg)

• array - Returns the passed in value.

• number/string/object/boolean - Returns a one element array containing the passed in argument.

to_string¶

string to_string(any $arg)

• string - Returns the passed in value.

• number/array/object/boolean - The JSON encoded value of the object. The JSON encoder should emit the encoded JSON value without adding any additional new lines.

to_number¶

number to_number(any $arg)

• string - Returns the parsed number. Any string that conforms to the json-number production is supported. Note that the floating number support will be implementation specific, but implementations should support at least IEEE 754-2008 binary64 (double precision) numbers, as this is generally available and widely used.

• number - Returns the passed in value.

• array - null

• object - null

• boolean - null

• null - null

type¶

string type(array|object|string|number|boolean|null $subject)

Returns the JavaScript type of the given $subject argument as a string value.

The return value MUST be one of the following:

• number

• string

• boolean

• array

• object

• null

values¶

array values(object $obj)

Returns the values of the provided object. Note that because JSON hashes are inheritently unordered, the values associated with the provided object obj are inheritently unordered. Implementations are not required to return values in any specific order. For example, given the input:

{"a": "first", "b": "second", "c": "third"}

The expression values(@) could have any of these return values:

• ["first", "second", "third"]

• ["first", "third", "second"]

• ["second", "first", "third"]

• ["second", "third", "first"]

• ["third", "first", "second"]

• ["third", "second", "first"]

If you would like a specific order, consider using the sort or sort_by functions.

Examples¶

search(foo | bar, {"foo": {"bar": "baz"}}) -> "baz"
search(foo[*].bar | [0], {
    "foo": [{"bar": ["first1", "second1"]},
            {"bar": ["first2", "second2"]}]}) -> ["first1", "second1"]
search(foo | [0], {"foo": [0, 1, 2]}) -> [0]