JSONPath

External

• https://goessner.net/articles/JsonPath/
• https://github.com/json-path/JsonPath
• https://support.smartbear.com/alertsite/docs/monitors/api/endpoint/jsonpath.html
• https://github.com/jayway/JsonPath

Internal

• JSON
• kubectl get JSONPath Support

Overview

JSONPath is a query language for JSON similar to XPath for XML. Some documentation describes it as a Java DSL for reading JSON documents, probably to address those cases where the implementation is made in Java.

JSONPath Expression

A JSONPath expression specifies a path to an element or a set of elements that are part of a JSON document.

.spec.containers[0].name

The expressions, including fields and values, are case-sensitive. Unlike XPath, JSONPath does not have operations for accessing parent or sibling nodes from a given nodes. An expression can be assembled using a series of syntax elements presented below.

$

$ represents the top-level element (or root) of the JSON document. The "$" is optional, the following are equivalent:

$.metadata
.metadata

Some JSONPath documentation mentions that even the leading dot can be omitted, but that may break some tools, as it is the case with kubectl JSONPath support.

Element Selection

There are two ways to select a specific child element relative to the parent element: the dot notation .field (or its variant ['field ']) and index-based selection. These two different forms are applied to JSON Objects and Arrays, respectively, given the fact that JSON has only these two types of collections. Both forms are called the child operator.

Object Fields Selection

.field

This is called "the dot notation". The expression selects the specified field in the parent JSON Object.

.metadata.resourceVersion

['field']

This is an equivalent variant of the dot notation that can used to select the specified field of a parent Object. It requires quotes around the field name and it is useful when the field name contains special characters such as spaces, or they begin with a character other than A..Za..z_.

['metadata']['resourceVersion']

kubectl JSONPath support supports this notation.

..field (Field Recursive Descent)

The expression searches for the specified field name recursively, starting with the specified path element, and returns a list of all values for this field name. It always returns a list if just one property is found. If not such field is found, the result is an empty list.

..name

Array Element Selection

Array elements are selected using 0-based indexes. All these are called subscript operators.

[0-based-index]

The expression selects the element whose index is specified between square brackets from a JSON Array.

[index1, index2, ...]

The expression selects the elements with the specified indexes from a JSON Array and returns a space-separated list. If the element with the specified index does not exist, the result is tool-dependent. For example, kubectl JSONPath support raises an error.

[start:end], [start:]

The expression selects the elements from the start index and up to, but not including, the end index. If end is omitted, it selects all elements from start until the end of the array. It returns a space-separated list. If the element with the specified index does not exist, the result is tool-dependent. For example, kubectl JSONPath support raises an error.

Some implementation support:

[start:end:step]

[:n]

The expression selects the first n elements of the array. It returns a space-separated list. If more elements than available are requested, the result is tool-dependent. For example, kubectl JSONPath support raises an error.

[-n:]

The expression selects the last n elements of the array. It returns a space-separated list. If more elements than available are requested, the result is tool-dependent. For example, kubectl JSONPath support raises an error.

Array Length

.array_name.length()

* (Wildcard)

Wildcard applies to both Object and Array elements and selects all fields/array elements, regardless of their names or indexes.

To apply it to an Object element:

.metadata.*

To apply it to an Array:

.status.conditions[*]

Note that dot notation can be applied to the result of the wildcard expression. If the expression is applied to an array, and there are more than one element in an array, a space separated list will be returned:

.status.conditions[*].lastTransitionTime

returns:

2021-03-03T18:40:00Z 2021-03-05T17:29:23Z 2021-03-05T17:29:23Z 2021-03-03T18:40:00Z

@

"@" is the JSONPath syntax element used in filter expressions and script expressions to refer to the current node being processed.

[,] (Union Operator)

The union operator allows alternate names or array indices as a set.

.items[*]['metadata.name', 'status.capacity']

Filter Expressions

?(expression)

A filter expression is a logical expression used to filter Object fields or array elements.

To select elements of an Array, combine the filter expression with [...]:

[?(expression)]

TODO: To select the fields of an Object, use it as such:

.?(expression)]

A filter expression selects all fields in an Object or all elements in an Array that match the specified filter. It returns a list.

@ can be used in the filter expression to represent the current node being processed - in this case, the array element being evaluated:

.status.conditions[?(@.status==False)]

The components of the filter expressions are:

• identifiers (@.status is an identifier)
• operators
• operands (strings and numbers). Strings must be quoted. Quote requirements (single or double quotes) depend on the tool.

Filter expressions can use $ to refer to elements outside the object being evaluated:

.store.book[?(@.price < $.expensive)]

An expression that specifies just a field name, such as [?(@.isbn)], matches all elements that have this field, regardless of the value.

Multiple Filter Expression on the Same Path

Multiple filter expressions can be applied to the same path.

.items[*].spec.volumes[?(@.name=="config-volume")]

will select to volume objects.

.items[?(@.metadata.name=="coredns-f9fd979d6-c9pg4")].spec.volumes[?(@.name=="config-volume")]

will select just one.

Filter Expression Operators

==

Equals to. String values must be quoted. The type of quote depends on the tool.

!=

Not Equal to. String values must be quoted. The type of quote depends on the tool.

!

Negate a filter.

&&

Logical AND, used to combine multiple filter expressions:

[?(@.category=='fiction' && @.price < 10)]

⚠️ As per kubectl 1.19.7, "&&" is not supported in JSONPath expressions:

error: error parsing jsonpath {.items[?(@.spec.claimRef.name=="something" && @.spec.claimRef.namespace=="somethingelse")].metadata.name}, unrecognized character in action: U+0026 '&'

||

Logical OR, used to combine multiple filter expressions:

[?(@.category=='fiction' || @.price < 10)]

Script Expressions

[(expression)]

A script expression can be used for both Objects and Arrays instead of explicit field names or indexes. @ can be referred from expression to represent the current node being processed.