JSONPath: Query Expressions for JSON
Extracted elements (31)
Bracket notation (e.g., $['store']['book'][0]) is treated as canonical and dot notation (e.g., $.store.book[0]) is defined as shorthand, ensuring a unique normative form for Normalized Paths and unambiguous serialization of node locations.
Implicit conversion from NodesType to ValueType is intentionally not defined because multiple extraction strategies exist for obtaining a value from a nodelist; the explicit value() function is provided instead to make this operation unambiguous and well-typed.
The original JSONPath proposal delegated filter expression evaluation to the host language runtime (e.g., JavaScript eval()), causing portability problems across environments. This specification removes all implementation-specific dependencies, making queries language-agnostic at the cost of some backwards compatibility.
JSONPath behavior is unpredictable when applied to JSON objects with duplicate member names; the semantics for name selection, wildcard, filter, and descendant segments may vary across implementations for such technically invalid JSON.
A function extension MUST be defined such that its evaluation is free of side effects; all possible evaluation orders and short-circuiting choices MUST lead to the same result.
A JSONPath implementation MUST raise an error for any query that is not well-formed or valid; well-formedness and validity are independent of the query argument and must be checked before application.
A JSONPath query MUST be encoded using UTF-8; the implementation decodes the UTF-8 form into Unicode scalar values as described in RFC 3629 before processing.
A syntactically valid segment MUST NOT produce errors during query execution; out-of-range indexes and type mismatches simply yield fewer (or zero) selected nodes rather than an error.
An implementation MUST NOT silently malfunction; if a valid query cannot be processed correctly due to resource constraints such as numeric overflow, the implementation MUST provide an explicit indication of overflow.
Any function expression in a query must be well-typed according to the declared type rules; an implementation MUST raise an error if a function expression is not well-typed (e.g., using a LogicalType result in a comparison).
Every top-level JSONPath query (except those inside filter expressions) MUST begin with the root identifier $.
For number comparisons in filter expressions, numbers expected to interoperate per I-JSON MUST compare using normal mathematical ordering; non-I-JSON numbers MAY use an implementation-specific ordering.
Integer numbers in a JSONPath query relevant to processing (e.g., index values and slice steps) MUST be within the I-JSON range of exact integer values: [-(2^53)+1, (2^53)-1].
Two member name strings MUST be considered equal if and only if they are identical sequences of Unicode scalar values; normalization operations MUST NOT be applied to either string prior to comparison.
A JSONPath expression consists of the root identifier $ (identifying the entire query argument as a single-node nodelist) followed by zero or more segments. The current node identifier @ is used within filter expressions to refer to the node being evaluated.
A Normalized Path is a unique JSONPath expression that identifies exactly one node in a query argument, using only single-quoted name selectors and non-negative index selectors within child segments ($['name'][0]...). Every node in a JSON value has exactly one Normalized Path.
A singular query is a JSONPath expression syntactically restricted (using only name and index segments) so that it always produces a nodelist of at most one node regardless of input; only singular queries may appear as comparables in filter comparison expressions.
Five built-in function extensions are defined: length() (string/array/object length as ValueType), count() (nodelist size), match() (full-string I-Regexp match, RFC 9485), search() (substring I-Regexp match), and value() (extracts a single-node nodelist value as ValueType).
The array slice selector has the form start:end:step, selecting array elements from start (inclusive) to end (exclusive) with the given step (default 1). When step is negative, elements are selected in reverse; when step is 0, no elements are selected.
The descendant segment ..[<selectors>] applies selectors to the input node and all its descendants recursively, enabling depth-first traversal of arbitrarily nested JSON structures.
The filter selector ?<logical-expr> iterates over elements/members of arrays and objects, selecting those for which the logical expression is true. It supports &&, ||, !, comparison operators (==, !=, <, <=, >, >=), existence tests, and function calls.
The function extension type system defines three types: ValueType (JSON values or the special result Nothing), LogicalType (LogicalTrue or LogicalFalse), and NodesType (nodelists). NodesType can be implicitly converted to LogicalType but not to ValueType.
The index selector selects an array element by a zero-based decimal integer; negative indices count backwards from the end (e.g., -1 is the last element). Out-of-range indices produce no selection and are not errors.
The name selector selects at most one object member value by name; string literals may be enclosed in single or double quotes with the same escape sequences, allowing access to member names containing spaces, dots, or other special characters.
The wildcard selector (*) selects all children of an object or array node; the order of object children in the result is deliberately unspecified since JSON objects are unordered, while array children appear in array order.
This document establishes the 'JSONPath Function Extensions' subregistry, allowing future registration of additional function extensions beyond the five built-in ones, each with a unique name and declared parameter/result types.
This document registers the media type application/jsonpath for identifying JSONPath expression strings, enabling their use in HTTP Content-Type and related headers.
Applications that construct JSONPath queries from user-supplied data risk query injection attacks analogous to SQL injection; user input incorporated into queries must be sanitized or constrained to prevent unintended node selection.
Crafted JSONPath queries can cause resource exhaustion; deeply nested descendant segments or pathological filter expressions may require exponential time or memory. Implementations should impose limits on query complexity and execution resources.
Security mechanisms that use JSONPath for access-control decisions must carefully validate both the queries they accept and the JSON values they process, since JSONPath's permissive error handling (empty result instead of error) may mask unexpected data structures.
String literals in JSONPath name selectors and filter expressions use single or double quote delimiters. Escape sequences include \b, \t, \n, \f, \r, \", \', \/, \\, and \uXXXX; characters above U+FFFF must be encoded as surrogate pairs (e.g., \uD83C\uDC41).