JavaScript Object Notation (JSON) Path

1.1. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

The grammatical rules in this document are to be interpreted as ABNF, as described in [RFC5234]. ABNF terminal values in this document define Unicode code points rather than their UTF-8 encoding. For example, the Unicode PLACE OF INTEREST SIGN (U+2318) would be defined in ABNF as %x2318.¶

The terminology of [RFC8259] applies.¶

Data Item:

A structure complying to the generic data model of JSON, i.e., composed of containers such as arrays and maps (JSON objects), and of atomic data such as null, true, false, numbers, and text strings.¶

Object:

Used in its generic sense, e.g., for programming language objects. When a JSON Object as defined in [RFC8259] is meant, we specifically say JSON Object.¶

Query:

Short name for JSONPath expression.¶

Argument:

Short name for the JSON data item a JSONPath expression is applied to.¶

Output Path:

A simple form of JSONPath expression that identifies a Position by providing a query that results in exactly that position. Similar to, but syntactically different from, a JSON Pointer [RFC6901].¶

Position:

A JSON data item identical to or nested within the JSON data item to which the query is applied to, expressed either by the value of that data item or by providing a JSONPath Output Path.¶

1.2. Inspired by XPath

A frequently emphasized advantage of XML is the availability of powerful tools to analyse, transform and selectively extract data from XML documents. [XPath] is one of these tools.¶

In 2007, the need for something solving the same class of problems for the emerging JSON community became apparent, specifically for:¶

• Finding data interactively and extracting them out of [RFC8259] data items without special scripting.¶
• Specifying the relevant parts of the JSON data in a request by a client, so the server can reduce the amount of data in its response, minimizing bandwidth usage.¶

So what does such a tool look like for JSON? When defining a JSONPath, how should expressions look?¶

The XPath expression¶

/store/book[1]/title

looks like¶

x.store.book[0].title

or¶

x['store']['book'][0]['title']

in popular programming languages such as JavaScript, Python and PHP, with a variable x holding the JSON data item. Here we observe that such languages already have a fundamentally XPath-like feature built in.¶

The JSONPath tool in question should:¶

• be naturally based on those language characteristics.¶
• cover only essential parts of XPath 1.0.¶
• be lightweight in code size and memory consumption.¶
• be runtime efficient.¶

1.3. Overview of JSONPath Expressions

JSONPath expressions always apply to a JSON data item in the same way as XPath expressions are used in combination with an XML document. Since a JSON data item is usually anonymous and doesn't necessarily have a "root member object", JSONPath used the abstract name $ to refer to the top level object of the data item.¶

JSONPath expressions can use the dot-notation¶

$.store.book[0].title

or the bracket-notation¶

$['store']['book'][0]['title']

for paths input to a JSONPath processor. [1] Where a JSONPath processor uses JSONPath expressions as output paths, these will always be converted to the more general bracket-notation. [2] Bracket notation is more general than dot notation and can serve as a canonical form when a JSONPath processor uses JSONPath expressions as output paths.¶

JSONPath allows the wildcard symbol * for member names and array indices. It borrows the descendant operator .. from [E4X] and the array slice syntax proposal [start:end:step] [SLICE] from ECMASCRIPT 4.¶

JSONPath was originally designed to employ an underlying scripting language for computing expressions. The present specification defines a simple expression language that is independent from any scripting language in use on the platform.¶

JSONPath can use expressions, written in parentheses: (<expr>), as an alternative to explicit names or indices as in:¶

$.store.book[(@.length-1)].title

The symbol @ is used for the current object. Filter expressions are supported via the syntax ?(<boolean expr>) as in¶

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

Here is a complete overview and a side by side comparison of the JSONPath syntax elements with their XPath counterparts.¶

XPath has a lot more to offer (location paths in unabbreviated syntax, operators and functions) than listed here. Moreover there is a significant difference how the subscript operator works in Xpath and JSONPath:¶

• Square brackets in XPath expressions always operate on the node set resulting from the previous path fragment. Indices always start at 1.¶
• With JSONPath, square brackets operate on the object or array addressed by the previous path fragment. Array indices always start at 0.¶

3.1. Overview

A JSONPath is a string which selects zero or more nodes of a piece of JSON. A valid JSONPath conforms to the ABNF syntax defined by this document.¶

A JSONPath MUST be encoded using UTF-8. To parse a JSONPath according to the grammar in this document, its UTF-8 form SHOULD first be decoded into Unicode code points as described in [RFC3629].¶

3.2. Terminology

A JSON value is logically a tree of nodes.¶

Each node holds a JSON value (as defined by [RFC8259]) of one of the types object, array, number, string, or one of the literals true, false, or null. The type of the JSON value held by a node is sometimes referred to as the type of the node.¶

3.3. Implementation

An implementation of this specification, from now on referred to simply as "an implementation", SHOULD takes two inputs, a JSONPath and a JSON value, and produce a possibly empty list of nodes of the JSON value which are selected by the JSONPath or an error (but not both).¶

If no node is selected and no error has occurred, an implementation MUST return an empty list of nodes.¶

Syntax errors in the JSONPath SHOULD be detected before selection is attempted since these errors do not depend on the JSON value. Therefore, an implementation SHOULD take a JSONPath and produce an optional syntax error and then, if and only if an error was not produced, SHOULD take a JSON value and produce a list of nodes or an error (but not both).¶

Alternatively, an implementation MAY take a JSONPath and a JSON value and produce a list of nodes or an optional error (but not both).¶

For any implementation, if a syntactically invalid JSONPath is provided, the implementation MUST return an error.¶

If a syntactially invalid JSON value is provided, any implementation SHOULD return an error.¶

3.4. Syntax

Syntactically, a JSONPath consists of a root selector ($), which selects the root node of a JSON value, followed by a possibly empty sequence of selectors.¶

json-path = root-selector *selector
root-selector = %x24               ; $ selects document root node

The syntax and semantics of each selector is defined below.¶

3.5. Semantics

The root selector $ not only selects the root node of the input document, but it also produces as output a list consisting of one node: the input document.¶

A selector may select zero or more nodes for further processing. A syntactically valid selector MUST NOT produce errors. This means that some operations which might be considered erroneous, such as indexing beyond the end of an array, simply result in fewer nodes being selected.¶

But a selector doesn't just act on a single node: each selector acts on a list of nodes and produces a list of nodes, as follows.¶

After the root selector, the remainder of the JSONPath is processed by passing lists of nodes from one selector to the next ending up with a list of nodes which is the result of applying the JSONPath to the input JSON value.¶

Each selector acts on its input list of nodes as follows. For each node in the list, the selector selects zero or more nodes, each of which is a descendant of the node or the node itself. The output list of nodes of a selector is the concatenation of the lists of selected nodes for each input node.¶

A specific, non-normative example will make this clearer. Suppose the input document is: {"a":[{"b":0},{"b":1},{"c":2}]}. As we will see later, the JSONPath $.a[*].b selects the following list of nodes: 0, 1. Let's walk through this in detail.¶

The JSONPath consists of $ followed by three selectors: .a, [*], and .b.¶

Firstly, $ selects the root node which is the input document. So the result is a list consisting of just the root node.¶

Next, .a selects from any input node of type object and selects any value of the input node corresponding to the key "a". The result is again a list of one node: [{"b":0},{"b":1},{"c":2}].¶

Next, [*] selects from any input node which is an array and selects all the elements of the input node. The result is a list of three nodes: {"b":0}, {"b":1}, and {"c":2}.¶

Finally, .b selects from any input node of type object with a key b and selects the value of the input node corresponding to that key. The result is a list containing 0, 1. This is the concatenation of three lists, two of length one containing 0, 1, respectively, and one of length zero.¶

As a consequence of this approach, if any of the selectors selects no nodes, then the whole JSONPath selects no nodes.¶

In what follows, the semantics of each selector are defined for each type of node.¶

3.6. Selectors

selector = dot-child              ; see below for alternatives
dot-child = %x2E dot-child-name / ; .<dot-child-name>
            %x2E %x2A             ; .*
dot-child-name = 1*(
                   %x2D /         ; -
                   DIGIT /
                   ALPHA /
                   %x5F /         ; _
                   %x80-10FFFF    ; any non-ASCII Unicode character
                 )
DIGIT =  %x30-39                  ; 0-9
ALPHA = %x41-5A / %x61-7A         ; A-Z / a-z

selector =/ union
union = %x5B ws union-elements ws %x5D ; [...]
ws = *%x20                             ; zero or more spaces
union-elements = union-element /
                 union-element ws %x2C ws union-elements
                                       ; ,-separated list

union-element = child ; see below for more alternatives
child = %x22 *double-quoted %x22 / ; "string"
        %x27 *single-quoted %x27   ; 'string'

double-quoted = dq-unescaped /
          escape (
              %x22 /          ; "    quotation mark  U+0022
              %x2F /          ; /    solidus         U+002F
              %x5C /          ; \    reverse solidus U+005C
              %x62 /          ; b    backspace       U+0008
              %x66 /          ; f    form feed       U+000C
              %x6E /          ; n    line feed       U+000A
              %x72 /          ; r    carriage return U+000D
              %x74 /          ; t    tab             U+0009
              %x75 4HEXDIG )  ; uXXXX                U+XXXX


      dq-unescaped = %x20-21 / %x23-5B / %x5D-10FFFF

single-quoted = sq-unescaped /
          escape (
              %x27 /          ; '    apostrophe      U+0027
              %x2F /          ; /    solidus         U+002F
              %x5C /          ; \    reverse solidus U+005C
              %x62 /          ; b    backspace       U+0008
              %x66 /          ; f    form feed       U+000C
              %x6E /          ; n    line feed       U+000A
              %x72 /          ; r    carriage return U+000D
              %x74 /          ; t    tab             U+0009
              %x75 4HEXDIG )  ; uXXXX                U+XXXX

      sq-unescaped = %x20-26 / %x28-5B / %x5D-10FFFF

escape = %x5C                 ; \

HEXDIG =  DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
                              ; case insensitive hex digit

union-element =/ array-index / array-slice

array-index = integer

integer = ["-"] ("0" / (DIGIT1 *DIGIT))
                            ; optional - followed by 0 or
                            ; sequence of digits with no leading zero
DIGIT1 = %x31-39            ; non-zero digit

array-slice = [ start ] ws ":" ws [ end ]
                   [ ws ":" ws [ step ] ]
start = integer
end = integer
step = integer

FUNCTION Normalize(i):
  IF i >= 0 THEN
    RETURN i
  ELSE
    RETURN len + i
  END IF

FUNCTION Bounds(start, end, step, len):
  n_start = Normalize(start)
  n_end = Normalize(end)

  IF step >= 0 THEN
    lower = MIN(MAX(n_start, 0), len)
    upper = MIN(MAX(n_end, 0), len)
  ELSE
    upper = MIN(MAX(n_start, -1), len-1)
    lower = MIN(MAX(n_end, -1), len-1)
  END IF

  RETURN (lower, upper)

IF step > 0 THEN

  i = lower
  WHILE i < upper:
    SELECT a(i)
    i = i + step
  END WHILE

ELSE if step < 0 THEN

  i = upper
  WHILE lower < i:
    SELECT a(i)
    i = i + step
  END WHILE

END IF