Python JSONPath extends theRFC 9535 specification with extra selectors and relaxed rules for convenience. If you need strict compliance with RFC 9535, passstrict=True when callingfindall(),finditer(), and similar functions. In strict mode, the syntax and behavior conform to the specification, and no non-standard extensions are registered by default. You can still add them manually if needed.

This guide first introduces the standard JSONPath syntax (see the RFC for the formal definition), then explains the non-standard extensions and their semantics.

fromjsonpathimportJSONPathEnvironmentfromjsonpath.function_extensionsimportStartsWithclassMyJSONPathEnvironment(JSONPathEnvironment):def__init__(self)->None:super().__init__(strict=True)defsetup_function_extensions(self)->None:super().setup_function_extensions()self.function_extensions["startswith"]=StartsWith()jsonpath=MyJSONPathEnvironment()query=jsonpath.compile("...")

JSONPath Terminology

Think of a JSON document as a tree, objects (mappings) and arrays can contain other objects, arrays, or scalar values. Each of these (object, array, or scalar) is anode in the tree. The outermost object or array is called theroot node.

In this guide, a JSON "document" may refer to:

• A file containing valid JSON text
• A Python string containing valid JSON text
• A Python object composed of dictionaries (or anyMapping), lists (or anySequence), strings, numbers, booleans, orNone

A JSONPath expression (aka "query") is made up of a sequence ofsegments. Each segment contains one or moreselectors:

• Asegment corresponds to a step in the path from one set of nodes to the next.
• Aselector describes how to choose nodes within that step (for example, by name, by index, or by wildcard).

What follows is a description of these selectors, starting with the standard ones defined inRFC 9535.

Standard selectors and identifiers

Root identifier

The root identifier,$, refers to the outermost node in the target document. This can be an object, an array, or a scalar value.

A query containing only the root identifier simply returns the entire input document.

Example query

$

{"categories":[{"id":1,"name":"fiction"},{"id":2,"name":"non-fiction"}]}

[{"categories":[{"id":1,"name":"fiction"},{"id":2,"name":"non-fiction"}]}]

Name selector

Aname selector matches the value of an object member by its key. You can write it in eithershorthand notation (.thing) orbracket notation (['thing'] or["thing"]).

Dot notation can be used when the property name is a valid identifier. Bracket notation is required when the property name contains spaces, special characters, or starts with a number.

Example query

$.book.title

{"book":{"title":"Moby Dick","author":"Herman Melville"}}

["Moby Dick"]

Index selector

The index selector selects an element from an array by its index. Indices are zero-based and enclosed in brackets,[0]. If the index is negative, items are selected from the end of the array.

Example query

$.categories[0].name

{"categories":[{"id":1,"name":"fiction"},{"id":2,"name":"non-fiction"}]}

["fiction"]

Wildcard selector

Thewildcard selector matches all member values of an object or all elements in an array. It can be written as.* (shorthand notation) or[*] (bracket notation).

Example query

$.categories[*].name

{"categories":[{"id":1,"name":"fiction"},{"id":2,"name":"non-fiction"}]}

["fiction","non-fiction"]

Slice selector

The slice selector allows you to select a range of elements from an array. A start index, ending index and step size are all optional and separated by colons,[start:end:step]. Negative indices count from the end of the array, just like standard Python slicing.

Example query

$.items[1:4:2]

{"items":["a","b","c","d","e","f"]}

["b","d"]

Filter selector

Filters allow you to remove nodes from a selection based on a Boolean expression,[?expression]. A filter expression evaluates each node in the context of either the root ($) or current (@) node.

When filtering a mapping-like object,@ identifies the current member value. When filtering a sequence-like object,@ identifies the current element.

Comparison operators include==,!=,<,>,<=, and>=. Logical operators&& (and) and|| (or) can combine terms, and parentheses can be used to group expressions.

A filter expression on its own - without a comparison - is treated as an existence test.

Example query

$..products[?(@.price < $.price_cap)]

{"price_cap":10,"products":[{"name":"apple","price":5},{"name":"orange","price":12},{"name":"banana","price":8}]}

[{"name":"apple","price":5},{"name":"banana","price":8}]

Filter expressions can also call predefinedfunction extensions.

More on segments

So far we've seen shorthand notation (.selector) and segments with just one selector ([selector]). Here we cover the descendant segment and segments with multiple selectors.

Segments with multiple selectors

A segment can include multiple selectors separated by commas and enclosed in square brackets ([selector, selector, ...]). Any valid selector (names, indices, slices, filters, or wildcards) can appear in the list.

Example query

$.store.book[0,2]

{"store":{"book":[{"title":"Book A","price":10},{"title":"Book B","price":12},{"title":"Book C","price":8}]}}

[{"title":"Book A","price":10},{"title":"Book C","price":8}]

Descendant segment

The descendant segment (..) visits all object member values and array elements under the current object or array, applying the selector or selectors that follow to each visited node. It must be followed by a shorthand selector (names, wildcards, etc.) or a bracketed list of one or more selectors.

Example query

$..price

{"store":{"book":[{"title":"Book A","price":10},{"title":"Book B","price":12}],"bicycle":{"color":"red","price":19.95}}}

[10,12,19.95]

Non-standard selectors and identifiers

The selectors and identifiers described in this section are an extension to the RFC 9535 specification. They are enabled by default. Setstrict=True when constructing aJSONPathEnvironment, callingfindall(),finditer(), etc. to disable all non-standard features.

Also note that whenstrict=False:

• The root identifier ($) is optional and paths starting with a dot (.) are OK..thing is the same as$.thing, as isthing and$["thing"].
• Leading and trailing whitespace is OK.
• Explicit comparisons toundefined (akamissing) are supported as well as implicit existence tests.

Key selector

New in version 2.0.0

The key selector,.~name or[~'name'], selects at most one name from an object member. It is syntactically similar to the standardname selector, with the addition of a tilde (~) prefix.

When applied to a JSON object, the key selector selects thename from an object member, if that name exists, or nothing if it does not exist. This complements the standard name selector, which select thevalue from a name/value pair.

When applied to an array or primitive value, the key selector selects nothing.

Key selector strings must follow the same processing semantics as name selector strings, as described insection 2.3.2.1 of RFC 9535.

Syntax

selector             = name-selector /                       wildcard-selector /                       slice-selector /                       index-selector /                       filter-selector /                       key-selector /                       keys-selector /                       keys-filter-selectorkey-selector         = "~" name-selectorchild-segment        = bracketed-selection /                       ("."                        (wildcard-selector /                         member-name-shorthand /                         member-key-shorthand))descendant-segment   = ".." (bracketed-selection /                             wildcard-selector /                             member-name-shorthand /                             member-key-shorthand)member-key-shorthand = "~" name-first *name-char

Examples

{"a":[{"b":"x","c":"z"},{"b":"y"}]}

Keys selector

New in version 0.6.0

The keys selector,~ or[~], selects all names from an object’s name/value members. This complements the standardwildcard selector, which selects all values from an object’s name/value pairs.

As with the wildcard selector, the order of nodes resulting from a keys selector is not stipulated.

When applied to an array or primitive value, the keys selector selects nothing.

The normalized path of a node selected using the keys selector useskey selector syntax.

Syntax

keys-selector       = "~"

Examples

{"a":[{"b":"x","c":"z"},{"b":"y"}]}

Keys filter selector

New in version 2.0.0

The keys filter selector selects names from an object’s name/value members. It is syntactically similar to the standardfilter selector, with the addition of a tilde (~) prefix.

~?<logical-expr>

Whereas the standard filter selector will produce a node for eachvalue from an object’s name/value members - when its expression evaluates to logical true - the keys filter selector produces a node for eachname in an object’s name/value members.

Logical expression syntax and semantics otherwise match that of the standard filter selector.@ still refers to the current member value. See also thecurrent key identifier.

When applied to an array or primitive value, the keys filter selector selects nothing.

The normalized path of a node selected using the keys filter selector useskey selector syntax.

Syntax

filter-selector     = "~?" S logical-expr

Examples

[{"a":[1,2,3],"b":[4,5]},{"c":{"x":[1,2]}},{"d":[1,2,3]}]

Singular query selector

New in version 2.0.0

The singular query selector consist of an embedded absolute singular query, the result of which is used as an object member name or array element index.

If the embedded query resolves to a string or int value, at most one object member value or array element value is selected. Otherwise the singular query selector selects nothing.

Syntax

selector                = name-selector /                          wildcard-selector /                          slice-selector /                          index-selector /                          filter-selector /                          singular-query-selectorsingular-query-selector = abs-singular-query

Examples

{"a":{"j":[1,2,3],"p":{"q":[4,5,6]}},"b":["j","p","q"],"c d":{"x":{"y":1}}}

Current key identifier

# is thecurrent key identifier.# will be the name of the current object member, or index of the current array element. This complements the current node identifier (@), which refers to a member value or array element, respectively.

It is a syntax error to follow the current key identifier with segments, as if it were a filter query.

When used as an argument to a function, the current key is ofValueType, and outside a function call it must be compared.

Syntax

comparable             = literal /                         singular-query / ; singular query value                         function-expr  / ; ValueType                         current-key-identifierfunction-argument      = literal /                         filter-query / ; (includes singular-query)                         logical-expr /                         function-expr /                         current-key-identifiercurrent-key-identifier = "#"

Examples

{"abc":[1,2,3],"def":[4,5],"abx":[6],"aby":[]}

Pseudo root identifier

New in version 0.11.0

The pseudo root identifier (^) behaves like the standard root identifier ($), but conceptually wraps the target JSON document in a single-element array. This allows the root document itself to be conditionally selected by filters.

Syntax

jsonpath-query             = (root-identifier / pseudo-root-identifier) segmentsroot-identifier            = "$"pseudo-root-identifier     = "^"

Examples

{"a":{"b":42},"n":7}

Filter context identifier

The filter context identifier (_) starts an embedded query, similar to the root identifier ($) and current node identifier (@), but targets JSON-like data passed as thefilter_context argument tofindall() andfinditer().

Syntax

current-node-identifier  = "@"extra-context-identifier = "_"filter-query        = rel-query / extra-context-query / jsonpath-queryrel-query           = current-node-identifier segmentsextra-context-query = extra-context-identifier segmentssingular-query      = rel-singular-query / abs-singular-query / extra-context-singular-queryrel-singular-query  = current-node-identifier singular-query-segmentsabs-singular-query  = root-identifier singular-query-segmentsextra-context-singular-query = extra-context-identifier singular-query-segments

Examples

{"a":[{"b":42},{"b":3}]}

{"c":42}

Non-standard operators

In addition to the operators described below, the standardlogical and operator (&&) is aliased asand, the standardlogical or operator (||) is aliased asor, andnull is aliased asnil andnone.

Also,true,false,null and their aliases can start with an upper case letter.

Membership operators

The membership operators test whether one value occurs within another.

An infix expression usingcontains evaluates to true if the right-hand side is a member of the left-hand side, and false otherwise.

• If the left-hand side is an object and the right-hand side is a string, the result is true if the object has a member with that name.
• If the left-hand side is an array, the result is true if any element of the array is equal to the right-hand side.
• For scalars (strings, numbers, booleans, null),contains always evaluates to false.

Thein operator is equivalent tocontains with operands reversed. This makescontains andin symmetric, so either form may be used depending on which reads more naturally in context.

A list literal is a comma separated list of JSONPath expression literals. List should appear on the left-hand side ofcontains or the right-hand side ofin.

Syntax

basic-expr          = paren-expr /                      comparison-expr /                      membership-expr /                      test-exprmembership-expr     = comparable S membership-op S comparablemembership-operator = "contains" / "in"membership-operand  = literal /                      singular-query / ; singular query value                      function-expr /  ; ValueType                      list-literallist-literal        = "[" S literal *(S "," S literal) S "]"

Examples

{"x":[{"a":["foo","bar"]},{"a":["bar"]}],"y":[{"a":{"foo":"bar"}},{"a":{"bar":"baz"}}],"z":[{"a":"foo"},{"a":"bar"}]}

Regex operator

=~ is an infix operator that matches the left-hand side with a regular expression literal on the right-hand side. Regular expression literals use a syntax similar to that found in JavaScript, where the pattern to match is surrounded by slashes,/pattern/, optionally followed by flags,/pattern/flags.

$..products[?(@.description =~ /.*trainers/i)]

Union and intersection operators

The union or concatenation operator,|, combines matches from two or more paths.

The intersection operator,&, produces matches that are common to both left and right paths.

Note that compound queries are not allowed inside filter expressions.

Syntax

jsonpath-query          = root-identifier segmentscompound-jsonpath-query = jsonpath-query compound-op jsonpath-querycompound-op             = "|" /                          "&"

Examples

$..products.*.price | $.price_cap

$.categories[?(@.name == 'footwear')].products.* & $.categories[?(@.name == 'headwear')].products.*