idnits 2.17.1 draft-ietf-jsonpath-base-05.txt: -(2): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(7): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 8 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 31 instances of too long lines in the document, the longest one being 22 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (25 April 2022) is 729 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 1820 -- Looks like a reference, but probably isn't: '3' on line 1815 -- Looks like a reference, but probably isn't: '2' on line 1815 == Missing Reference: '-1' is mentioned on line 1817, but not defined -- Looks like a reference, but probably isn't: '1' on line 1820 -- Looks like a reference, but probably isn't: '5' on line 1438 -- Looks like a reference, but probably isn't: '4' on line 1300 == Missing Reference: '-2' is mentioned on line 897, but not defined -- Looks like a reference, but probably isn't: '6' on line 1310 -- Looks like a reference, but probably isn't: '7' on line 1311 == Outdated reference: A later version (-04) exists of draft-bormann-jsonpath-iregexp-03 Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JSONPath WG S. Gössner, Ed. 3 Internet-Draft Fachhochschule Dortmund 4 Intended status: Standards Track G. Normington, Ed. 5 Expires: 27 October 2022 6 C. Bormann, Ed. 7 Universität Bremen TZI 8 25 April 2022 10 JSONPath: Query expressions for JSON 11 draft-ietf-jsonpath-base-05 13 Abstract 15 JSONPath defines a string syntax for selecting and extracting values 16 within a JavaScript Object Notation (JSON, RFC 8259) value. 18 About This Document 20 This note is to be removed before publishing as an RFC. 22 Status information for this document may be found at 23 https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/. 25 Discussion of this document takes place on the JSON Path Working 26 Group mailing list (mailto:jsonpath@ietf.org), which is archived at 27 https://mailarchive.ietf.org/arch/browse/jsonpath/. 29 Source for this draft and an issue tracker can be found at 30 https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-base. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on 27 October 2022. 49 Copyright Notice 51 Copyright (c) 2022 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 56 license-info) in effect on the date of publication of this document. 57 Please review these documents carefully, as they describe your rights 58 and restrictions with respect to this document. Code Components 59 extracted from this document must include Revised BSD License text as 60 described in Section 4.e of the Trust Legal Provisions and are 61 provided without warranty as described in the Revised BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 67 1.2. History . . . . . . . . . . . . . . . . . . . . . . . . . 5 68 1.3. Overview of JSONPath Expressions . . . . . . . . . . . . 5 69 2. JSONPath Examples . . . . . . . . . . . . . . . . . . . . . . 7 70 3. JSONPath Syntax and Semantics . . . . . . . . . . . . . . . . 9 71 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 9 72 3.2. Processing Model . . . . . . . . . . . . . . . . . . . . 10 73 3.3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 11 74 3.4. Semantics . . . . . . . . . . . . . . . . . . . . . . . . 11 75 3.5. Selectors . . . . . . . . . . . . . . . . . . . . . . . . 12 76 3.5.1. Root Selector . . . . . . . . . . . . . . . . . . . . 13 77 3.5.2. Dot Selector . . . . . . . . . . . . . . . . . . . . 14 78 3.5.3. Dot Wildcard Selector . . . . . . . . . . . . . . . . 15 79 3.5.4. Index Selector . . . . . . . . . . . . . . . . . . . 15 80 3.5.5. Index Wildcard Selector . . . . . . . . . . . . . . . 19 81 3.5.6. Array Slice Selector . . . . . . . . . . . . . . . . 20 82 3.5.7. Descendant Selector . . . . . . . . . . . . . . . . . 25 83 3.5.8. Filter Selector . . . . . . . . . . . . . . . . . . . 28 84 3.5.9. List Selector . . . . . . . . . . . . . . . . . . . . 31 85 3.6. Semantics of null . . . . . . . . . . . . . . . . . . . . 33 86 3.7. Normalized Paths . . . . . . . . . . . . . . . . . . . . 34 87 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 88 4.1. Registration of Media Type application/jsonpath . . . . . 36 89 5. Security Considerations . . . . . . . . . . . . . . . . . . . 37 90 5.1. Attack vectors on JSONPath Implementations . . . . . . . 37 91 5.2. Attacks on Security Mechanisms that Employ JSONPath . . . 38 92 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 93 6.1. Normative References . . . . . . . . . . . . . . . . . . 38 94 6.2. Informative References . . . . . . . . . . . . . . . . . 39 95 Appendix A. Inspired by XPath . . . . . . . . . . . . . . . . . 39 96 A.1. JSONPath and XPath . . . . . . . . . . . . . . . . . . . 41 98 Appendix B. JSON Pointer . . . . . . . . . . . . . . . . . . . . 44 99 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 44 100 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 44 101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 45 103 1. Introduction 105 JavaScript Object Notation (JSON, [RFC8259]) is a popular 106 representation format for structured data values. JSONPath defines a 107 string syntax for identifying values within a JSON value. 109 JSONPath is not intended as a replacement for, but as a more powerful 110 companion to, JSON Pointer [RFC6901]. See Appendix B. 112 1.1. Terminology 114 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 115 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 116 "OPTIONAL" in this document are to be interpreted as described in 117 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 118 capitals, as shown here. 120 The grammatical rules in this document are to be interpreted as ABNF, 121 as described in [RFC5234]. ABNF terminal values in this document 122 define Unicode code points rather than their UTF-8 encoding. For 123 example, the Unicode PLACE OF INTEREST SIGN (U+2318) would be defined 124 in ABNF as %x2318. 126 The terminology of [RFC8259] applies except where clarified below. 127 The terms "Primitive" and "Structured" are used to group the types as 128 in Section 1 of [RFC8259]. Definitions for "Object", "Array", 129 "Number", and "String" remain unchanged. Importantly "object" and 130 "array" in particular do not take on a generic meaning, such as they 131 would in a general programming context. 133 Additional terms used in this specification are defined below. 135 Value: As per [RFC8259], a structure complying to the generic data 136 model of JSON, i.e., composed of components such as structured 137 values, namely JSON objects and arrays, and primitive data, namely 138 numbers and text strings as well as the special values null, true, 139 and false. 141 Member: A name/value pair in an object. (Not itself a value.) 143 Name: The name in a name/value pair constituting a member. (Also 144 known as "key", "tag", or "label".) This is also used in 145 [RFC8259], but that specification does not formally define it. It 146 is included here for completeness. 148 Element: A value in an array. (Not to be confused with XML 149 element.) 151 Index: A non-negative integer that identifies a specific element in 152 an array. Note that the term _indexing_ is also used for 153 accessing elements using negative integers (Section "Semantics"), 154 and for accessing member values in an object using their member 155 name. 157 Query: Short name for JSONPath expression. 159 Argument: Short name for the value a JSONPath expression is applied 160 to. 162 Node: The pair of a value along with its location within the 163 argument. 165 Root Node: The unique node whose value is the entire argument. 167 Children (of a node): If the node is an array, each of its elements, 168 or if the node is an object, each its member values (but not its 169 member names). If the node is neither an array nor an object, it 170 has no descendants. 172 Descendants (of a node): The children of the node, together with the 173 children of its children, and so forth recursively. More 174 formally, the descendants relation between nodes is the transitive 175 closure of the children relation. 177 Nodelist: A list of nodes. The output of applying a query to an 178 argument is manifested as a list of nodes. While this list can be 179 represented in JSON, e.g. as an array, the nodelist is an abstract 180 concept unrelated to JSON values. 182 Normalized Path: A simple form of JSONPath expression that 183 identifies a node by providing a query that results in exactly 184 that node. Similar to, but syntactically different from, a JSON 185 Pointer [RFC6901]. 187 Singular Path: A JSONPath expression built from selectors which each 188 select at most one node. 190 For the purposes of this specification, a value as defined by 191 [RFC8259] is also viewed as a tree of nodes. Each node, in turn, 192 holds a value. Further nodes within each value are the elements of 193 arrays and the member values of objects and are themselves values. 194 (The type of the value held by a node may also be referred to as the 195 type of the node.) 197 A query is applied to an argument, and the output is a nodelist. 199 1.2. History 201 This document picks up Stefan Goessner's popular JSONPath proposal 202 dated 2007-02-21 [JSONPath-orig] and provides a normative definition 203 for it. 205 Appendix A describes how JSONPath was inspired by XML's XPath 206 [XPath]. 208 JSONPath was intended as a light-weight companion to JSON 209 implementations on platforms such as PHP and JavaScript, so instead 210 of defining its own expression language like XPath did, JSONPath 211 delegated this to the expression language of the platform. While the 212 languages in which JSONPath is used do have significant 213 commonalities, over time this caused non-portability of JSONPath 214 expressions between the ensuing platform-specific dialects. 216 The present specification intends to remove platform dependencies and 217 serve as a common JSONPath specification that can be used across 218 platforms. Obviously, this means that backwards compatibility could 219 not always be achieved; a design principle of this specification is 220 to go with a "consensus" between implementations even if it is rough, 221 as long as that does not jeopardize the objective of obtaining a 222 usable, stable JSON query language. 224 1.3. Overview of JSONPath Expressions 226 JSONPath expressions are applied to a JSON value, the _argument_. 227 Within the JSONPath expression, the abstract name $ is used to refer 228 to the _root node_ of the argument, i.e., to the argument as a whole. 230 JSONPath expressions can use the _dot notation_ 232 $.store.book[0].title 234 or the more general _bracket notation_ 236 $['store']['book'][0]['title'] 237 to build paths that are input to a JSONPath implementation. 239 JSONPath allows the wildcard symbol * to select any member of an 240 object or any element of an array (Section 3.5.3). The descendant 241 operator .. selects all the descendants (Section 3.5.7) of a node. 242 The array slice syntax [start:end:step] allows selecting a regular 243 selection of an element from an array, giving a start position, an 244 end position, and possibly a step value that moves the position from 245 the start to the end (Section 3.5.6). 247 Filter expressions are supported via the syntax ?() as 248 in 250 $.store.book[?(@.price < 10)].title 252 Table 1 provides a quick overview of the JSONPath syntax elements. 254 +===========+=============================================+ 255 | JSONPath | Description | 256 +===========+=============================================+ 257 | $ | the root node (Section 3.5.1) | 258 +-----------+---------------------------------------------+ 259 | @ | the current node: within filter selectors | 260 | | (Section 3.5.8) | 261 +-----------+---------------------------------------------+ 262 | .name | child selectors for JSON objects: dot | 263 | | selector (Section 3.5.2) | 264 +-----------+---------------------------------------------+ 265 | ['name'] | child selectors for JSON objects: index | 266 | | selector (Section 3.5.4) | 267 +-----------+---------------------------------------------+ 268 | .. | descendants: descendant selector | 269 | | (Section 3.5.7) | 270 +-----------+---------------------------------------------+ 271 | * | all child member values and array elements: | 272 | | dot wildcard selector (Section 3.5.3), | 273 | | index wildcard selector (Section 3.5.5) | 274 +-----------+---------------------------------------------+ 275 | [3] | index (subscript) selector (Section 3.5.4): | 276 | | index current node as an array (from 0) | 277 +-----------+---------------------------------------------+ 278 | [..,..] | list selector (Section 3.5.9): allow | 279 | | combining selector styles | 280 +-----------+---------------------------------------------+ 281 | [0:100:5] | array slice selector (Section 3.5.6): | 282 | | start:end:step | 283 +-----------+---------------------------------------------+ 284 | ?... | filter selector (Section 3.5.8) | 285 +-----------+---------------------------------------------+ 286 | () | expression: within filter selectors | 287 | | (Section 3.5.8) | 288 +-----------+---------------------------------------------+ 290 Table 1: Overview of JSONPath 292 2. JSONPath Examples 294 This section provides some more examples for JSONPath expressions. 295 The examples are based on the simple JSON value shown in Figure 1, 296 which was patterned after a typical XML example representing a 297 bookstore (that also has bicycles). 299 { "store": { 300 "book": [ 301 { "category": "reference", 302 "author": "Nigel Rees", 303 "title": "Sayings of the Century", 304 "price": 8.95 305 }, 306 { "category": "fiction", 307 "author": "Evelyn Waugh", 308 "title": "Sword of Honour", 309 "price": 12.99 310 }, 311 { "category": "fiction", 312 "author": "Herman Melville", 313 "title": "Moby Dick", 314 "isbn": "0-553-21311-3", 315 "price": 8.99 316 }, 317 { "category": "fiction", 318 "author": "J. R. R. Tolkien", 319 "title": "The Lord of the Rings", 320 "isbn": "0-395-19395-8", 321 "price": 22.99 322 } 323 ], 324 "bicycle": { 325 "color": "red", 326 "price": 19.95 327 } 328 } 329 } 331 Figure 1: Example JSON value 333 The examples in Table 2 use the expression mechanism to obtain the 334 number of elements in an array, to test for the presence of a member 335 in a object, and to perform numeric comparisons of member values with 336 a constant. 338 +========================+===================================+ 339 | JSONPath | Result | 340 +========================+===================================+ 341 | $.store.book[*].author | the authors of all books in the | 342 | | store | 343 +------------------------+-----------------------------------+ 344 | $..author | all authors | 345 +------------------------+-----------------------------------+ 346 | $.store.* | all things in store, which are | 347 | | some books and a red bicycle | 348 +------------------------+-----------------------------------+ 349 | $.store..price | the prices of everything in the | 350 | | store | 351 +------------------------+-----------------------------------+ 352 | $..book[2] | the third book | 353 +------------------------+-----------------------------------+ 354 | $..book[-1] | the last book in order | 355 +------------------------+-----------------------------------+ 356 | $..book[0,1] | the first two books | 357 | $..book[:2] | | 358 +------------------------+-----------------------------------+ 359 | $..book[?(@.isbn)] | filter all books with isbn number | 360 +------------------------+-----------------------------------+ 361 | $..book[?(@.price<10)] | filter all books cheaper than 10 | 362 +------------------------+-----------------------------------+ 363 | $..* | all elements in XML document; all | 364 | | member values and array elements | 365 | | contained in input value | 366 +------------------------+-----------------------------------+ 368 Table 2: Example JSONPath expressions applied to the 369 example JSON value 371 3. JSONPath Syntax and Semantics 373 3.1. Overview 375 A JSONPath query is a string which selects zero or more nodes of a 376 piece of JSON. 378 A query MUST be encoded using UTF-8. The grammar for queries given 379 in this document assumes that its UTF-8 form is first decoded into 380 Unicode code points as described in [RFC3629]; implementation 381 approaches that lead to an equivalent result are possible. 383 A string to be used as a JSONPath query needs to be _well-formed_ and 384 _valid_. A string is a well-formed JSONPath query if it conforms to 385 the ABNF syntax in this document. A well-formed JSONPath query is 386 valid if it also fulfills all semantic requirements posed by this 387 document. 389 To be valid, integer numbers in the JSONPath query that are relevant 390 to the JSONPath processing (e.g., index values and steps) MUST be 391 within the range of exact values defined in I-JSON [RFC7493], namely 392 within the interval [-(2^53)+1, (2^53)-1]). 394 To be valid, strings on the right hand side of the =~ regex matching 395 operator need to conform to [I-D.draft-bormann-jsonpath-iregexp]. 397 The well-formedness and the validity of JSONPath queries are 398 independent of the JSON value the query is applied to; no further 399 errors can be raised during application of the query to a value. 401 Obviously, an implementation can still fail when executing a JSONPath 402 query, e.g., because of resource depletion, but this is not modeled 403 in the present specification. However, the implementation MUST NOT 404 silently malfunction. Specifically, if a valid JSONPath query is 405 evaluated against a structured value whose size doesn't fit in the 406 range of exact values, interfering with the correct interpretation of 407 the query, the implementation MUST provide an indication of overflow. 409 (Readers familiar with the HTTP error model may be reminded of 400 410 type errors when pondering well-formedness and validity, while 411 resource depletion and related errors are comparable to 500 type 412 errors.) 414 3.2. Processing Model 416 In this specification, the semantics of a JSONPath query are defined 417 in terms of a _processing model_. That model is not prescriptive of 418 the internal workings of an implementation: Implementations may wish 419 (or need) to design a different process that yields results that are 420 consistent with this model. 422 In the processing model, a valid query is executed against a value, 423 the _argument_, and produces a list of zero or more nodes of the 424 value. 426 The query is a sequence of zero or more _selectors_, each of which is 427 applied to the result of the previous selector and provides input to 428 the next selector. These results and inputs take the form of a 429 _nodelist_, i.e., a sequence of zero or more nodes. 431 The nodelist going into the first selector contains a single node, 432 the argument. The nodelist resulting from the last selector is 433 presented as the result of the query; depending on the specific API, 434 it might be presented as an array of the JSON values at the nodes, an 435 array of Normalized Paths referencing the nodes, or both -- or some 436 other representation as desired by the implementation. Note that the 437 API must be capable of presenting an empty nodelist as the result of 438 the query. 440 A selector performs its function on each of the nodes in its input 441 nodelist, during such a function execution, such a node is referred 442 to as the "current node". Each of these function executions produces 443 a nodelist, which are then concatenated into the result of the 444 selector. 446 The processing within a selector may execute nested queries, which 447 are in turn handled with the processing model defined here. 448 Typically, the argument to that query will be the current node of the 449 selector or a set of nodes subordinate to that current node. 451 3.3. Syntax 453 Syntactically, a JSONPath query consists of a root selector ($), 454 which stands for a nodelist that contains the root node of the 455 argument, followed by a possibly empty sequence of _selectors_. 457 json-path = root-selector *(S (dot-selector / 458 dot-wild-selector / 459 index-selector / 460 index-wild-selector / 461 slice-selector / 462 descendant-selector / 463 filter-selector / 464 list-selector)) 466 The syntax and semantics of each selector is defined below. 468 3.4. Semantics 470 The root selector $ not only selects the root node of the argument, 471 but it also produces as output a list consisting of one node: the 472 argument itself. 474 A selector may select zero or more nodes for further processing. A 475 syntactically valid selector MUST NOT produce errors. This means 476 that some operations that might be considered erroneous, such as 477 indexing beyond the end of an array, simply result in fewer nodes 478 being selected. 480 But a selector doesn't just act on a single node: a selector acts on 481 each of the nodes in its input nodelist and concatenates the 482 resultant nodelists to form the result nodelist of the selector. 484 For each node in the list, the selector selects zero or more nodes, 485 each of which is a descendant of the node or the node itself. 487 For instance, with the argument {"a":[{"b":0},{"b":1},{"c":2}]}, the 488 query $.a[*].b selects the following list of nodes: 0, 1 (denoted 489 here by their value). Let's walk through this in detail. 491 The query consists of $ followed by three selectors: .a, [*], and .b. 493 Firstly, $ selects the root node which is the argument. So the 494 result is a list consisting of just the root node. 496 Next, .a selects from any input node of type object and selects the 497 node of any member value of the input node corresponding to the 498 member name "a". The result is again a list of one node: 499 [{"b":0},{"b":1},{"c":2}]. 501 Next, [*] selects from an input node of type array all its elements 502 (if the input note were of type object, it would select all its 503 member values, but not the member names). The result is a list of 504 three nodes: {"b":0}, {"b":1}, and {"c":2}. 506 Finally, .b selects from any input node of type object with a member 507 name b and selects the node of the member value of the input node 508 corresponding to that name. The result is a list containing 0, 1. 509 This is the concatenation of three lists, two of length one 510 containing 0, 1, respectively, and one of length zero. 512 As a consequence of this approach, if any of the selectors selects no 513 nodes, then the whole query selects no nodes. 515 In what follows, the semantics of each selector are defined for each 516 type of node. 518 3.5. Selectors 520 A JSONPath query consists of a sequence of selectors. Valid 521 selectors are 523 * Root selector $ (used at the start of a query and in expressions) 525 * Dot selector ., used with object member names exclusively. 527 * Dot wildcard selector .*. 529 * Index selector [], where is either a (possibly 530 negative, see Section "Semantics") array index or an object member 531 name. 533 * Index wildcard selector [*]. 535 * Array slice selector [::], where the optional 536 values , , and are integer literals. 538 * Descendants selector ... 540 * List selector [,,...,], holding a comma 541 separated list of index and slice selectors. 543 * Filter selector [?()] 545 * Current item selector @ (used in expressions) 547 3.5.1. Root Selector 549 Syntax 551 Every valid JSONPath query MUST begin with the root selector $. 553 root-selector = "$" 555 Semantics 557 The Argument -- the root JSON value -- becomes the root node, which 558 is addressed by the root selector $. 560 Examples 562 JSON document: 564 {"k": "v"} 566 Queries: 568 +=======+============+=============+===========+ 569 | Query | Result | Result Path | Comment | 570 +=======+============+=============+===========+ 571 | $ | {"k": "v"} | $ | Root node | 572 +-------+------------+-------------+-----------+ 574 Table 3: Root selector examples 576 3.5.2. Dot Selector 578 Syntax 580 A dot selector starts with a dot . followed by an object's member 581 name. 583 dot-selector = "." dot-member-name 584 dot-member-name = name-first *name-char 585 name-first = 586 ALPHA / 587 "_" / ; _ 588 %x80-10FFFF ; any non-ASCII Unicode character 589 name-char = DIGIT / name-first 591 DIGIT = %x30-39 ; 0-9 592 ALPHA = %x41-5A / %x61-7A ; A-Z / a-z 594 Member names containing characters other than allowed by dot-selector 595 -- such as space ` , minus-, or dot.characters -- MUST NOT be used 596 with thedot-selector. (Such member names can be addressed by 597 theindex-selector` instead.) 599 Semantics 601 The dot-selector selects the node of the member value corresponding 602 to the member name from any JSON object in its input nodelist. It 603 selects no nodes from any other JSON value. 605 Examples 607 JSON document: 609 {"j": {"k": 3}} 611 Queries: 613 +=======+==========+==============+==============================+ 614 | Query | Result | Result Paths | Comment | 615 +=======+==========+==============+==============================+ 616 | $.j | {"k": 3} | $['j'] | Named value of an object | 617 +-------+----------+--------------+------------------------------+ 618 | $.j.k | 3 | $['j']['k'] | Named value in nested object | 619 +-------+----------+--------------+------------------------------+ 621 Table 4: Dot selector examples 623 3.5.3. Dot Wildcard Selector 625 Syntax 627 The dot wildcard selector has the form .* as defined in the following 628 syntax: 630 dot-wild-selector = "." "*" ; dot followed by asterisk 632 Semantics 634 A dot-wild-selector acts as a wildcard by selecting the nodes of all 635 member values of an object in its input nodelist as well as all 636 element nodes of an array in its input nodelist. Applying the dot- 637 wild-selector to a primitive JSON value (number, string, or 638 true/false/null) selects no node. 640 Examples 642 JSON document: 644 { 645 "o": {"j": 1, "k": 2}, 646 "a": [5, 3] 647 } 649 Queries: 651 +=======+========+==============+=============+ 652 | Query | Result | Result Paths | Comment | 653 +=======+========+==============+=============+ 654 | $.o.* | 1 | $['o']['j'] | Object | 655 | | 2 | $['o']['k'] | values | 656 +-------+--------+--------------+-------------+ 657 | $.o.* | 2 | $['o']['k'] | Alternative | 658 | | 1 | $['o']['j'] | result | 659 +-------+--------+--------------+-------------+ 660 | $.a.* | 5 | $['a'][0] | Array | 661 | | 3 | $['a'][1] | members | 662 +-------+--------+--------------+-------------+ 664 Table 5: Dot wildcard selector examples 666 3.5.4. Index Selector 667 Syntax 669 An index selector [] addresses at most one object member value 670 or at most one array element value. 672 index-selector = "[" S (quoted-member-name / element-index) S "]" 674 Applying the index-selector to an object value in its input nodelist, 675 a quoted-member-name string is required to select the corresponding 676 member value. In contrast to JSON, the JSONPath syntax allows 677 strings to be enclosed in _single_ or _double_ quotes. 679 quoted-member-name = string-literal 681 string-literal = %x22 *double-quoted %x22 / ; "string" 682 %x27 *single-quoted %x27 ; 'string' 684 double-quoted = unescaped / 685 %x27 / ; ' 686 ESC %x22 / ; \" 687 ESC escapable 689 single-quoted = unescaped / 690 %x22 / ; " 691 ESC %x27 / ; \' 692 ESC escapable 694 ESC = %x5C ; \ backslash 696 unescaped = %x20-21 / ; s. RFC 8259 697 %x23-26 / ; omit " 698 %x28-5B / ; omit ' 699 %x5D-10FFFF ; omit \ 701 escapable = ( %x62 / %x66 / %x6E / %x72 / %x74 / ; \b \f \n \r \t 702 ; b / ; BS backspace U+0008 703 ; t / ; HT horizontal tab U+0009 704 ; n / ; LF line feed U+000A 705 ; f / ; FF form feed U+000C 706 ; r / ; CR carriage return U+000D 707 "/" / ; / slash (solidus) U+002F 708 "\" / ; \ backslash (reverse solidus) U+005C 709 (%x75 hexchar) ; uXXXX U+XXXX 710 ) 712 hexchar = non-surrogate / (high-surrogate "\" %x75 low-surrogate) 713 non-surrogate = ((DIGIT / "A"/"B"/"C" / "E"/"F") 3HEXDIG) / 714 ("D" %x30-37 2HEXDIG ) 715 high-surrogate = "D" ("8"/"9"/"A"/"B") 2HEXDIG 716 low-surrogate = "D" ("C"/"D"/"E"/"F") 2HEXDIG 718 HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" 720 ; Task from 2021-06-15 interim: update ABNF later 722 Applying the index-selector to an array, a numerical element-index is 723 required to select the corresponding element. JSONPath allows it to 724 be negative (see Section "Semantics"). 726 element-index = int ; decimal integer 728 int = ["-"] ( "0" / (DIGIT1 *DIGIT) ) ; - optional 729 DIGIT1 = %x31-39 ; 1-9 non-zero digit 731 Notes: 1. double-quoted strings follow the JSON string syntax 732 (Section 7 of [RFC8259]); single-quoted strings follow an analogous 733 pattern (Section "Syntax"). 2. An element-index is an integer (in 734 base 10, as in JSON numbers). 3. As in JSON numbers, the syntax does 735 not allow octal-like integers with leading zeros such as 01 or -01. 737 Semantics 739 A quoted-member-name string MUST be converted to a member name by 740 removing the surrounding quotes and replacing each escape sequence 741 with its equivalent Unicode character, as in the table below: 743 +=================+===================+=============================+ 744 | Escape Sequence | Unicode Character | Description | 745 +=================+===================+=============================+ 746 | \b | U+0008 | BS backspace | 747 +-----------------+-------------------+-----------------------------+ 748 | \t | U+0009 | HT horizontal tab | 749 +-----------------+-------------------+-----------------------------+ 750 | \n | U+000A | LF line feed | 751 +-----------------+-------------------+-----------------------------+ 752 | \f | U+000C | FF form feed | 753 +-----------------+-------------------+-----------------------------+ 754 | \r | U+000D | CR carriage return | 755 +-----------------+-------------------+-----------------------------+ 756 | \" | U+0022 | quotation mark | 757 +-----------------+-------------------+-----------------------------+ 758 | \' | U+0027 | apostrophe | 759 +-----------------+-------------------+-----------------------------+ 760 | \/ | U+002F | slash (solidus) | 761 +-----------------+-------------------+-----------------------------+ 762 | \\ | U+005C | backslash (reverse | 763 | | | solidus) | 764 +-----------------+-------------------+-----------------------------+ 765 | \uXXXX | U+XXXX | unicode character | 766 +-----------------+-------------------+-----------------------------+ 768 Table 6: Escape Sequence Replacements 770 The index-selector applied with a quoted-member-name to an object 771 selects the node of the corresponding member value from it, if and 772 only if that object has a member with that name. Nothing is selected 773 from a value that is not a object. 775 Array indexing via element-index is a way of selecting a particular 776 array element using a zero-based index. For example, selector [0] 777 selects the first and selector [4] the fifth element of a 778 sufficiently long array. 780 A negative element-index counts from the array end. For example, 781 selector [-1] selects the last and selector [-2] selects the 782 penultimate element of an array with at least two elements. As with 783 non-negative indexes, it is not an error if such an element does not 784 exist; this simply means that no element is selected. 786 Examples 788 JSON document: 790 { 791 "o": {"j j": {"k.k": 3}}, 792 "a": ["a","b"] 793 } 795 Queries: 797 +===================+========+==============+==================+ 798 | Query | Result | Result Paths | Comment | 799 +===================+========+==============+==================+ 800 | $.o['j j']['k.k'] | 3 | $['o']['j | Named value in | 801 | | | ']['k.k'] | nested object | 802 +-------------------+--------+--------------+------------------+ 803 | $.o["j j"]["k.k"] | 3 | $['o']['j | Named value in | 804 | | | ']['k.k'] | nested object | 805 +-------------------+--------+--------------+------------------+ 806 | $.a[1] | "b" | $['a'][1] | Member of array | 807 +-------------------+--------+--------------+------------------+ 808 | $.a[-2] | "a" | $['a'][0] | Member of array, | 809 | | | | from the end | 810 +-------------------+--------+--------------+------------------+ 812 Table 7: Index selector examples 814 3.5.5. Index Wildcard Selector 816 Syntax 818 The index wildcard selector has the form [*]. 820 index-wild-selector = "[" "*" "]" ; asterisk enclosed by brackets 822 Semantics 824 An index-wild-selector selects the nodes of all member values of an 825 object as well as of all elements of an array. Applying the index- 826 wild-selector to a primitive JSON value (such as a number, string, or 827 true/false/null) selects no node. 829 The index-wild-selector behaves identically to the dot-wild-selector. 831 Examples 833 JSON document: 835 { 836 "o": {"j": 1, "k": 2}, 837 "a": [5, 3] 838 } 840 Queries: 842 +=========+========+==============+=============+ 843 | Query | Result | Result Paths | Comment | 844 +=========+========+==============+=============+ 845 | $.o.[*] | 1 | $['o']['j'] | Object | 846 | | 2 | $['o']['k'] | values | 847 +---------+--------+--------------+-------------+ 848 | $.o.[*] | 2 | $['o']['k'] | Alternative | 849 | | 1 | $['o']['j'] | result | 850 +---------+--------+--------------+-------------+ 851 | $.a.[*] | 5 | $['a'][0] | Array | 852 | | 3 | $['a'][1] | members | 853 +---------+--------+--------------+-------------+ 855 Table 8: Index wildcard selector examples 857 3.5.6. Array Slice Selector 859 Syntax 861 The array slice selector has the form [::]. It 862 selects elements starting at index , ending at -- but not 863 including -- , while incrementing by step. 865 slice-selector = "[" S slice-index S "]" 867 slice-index = [start S] ":" S [end S] [":" [S step ]] 869 start = int ; included in selection 870 end = int ; not included in selection 871 step = int ; default: 1 873 B = %x20 / ; Space 874 %x09 / ; Horizontal tab 875 %x0A / ; Line feed or New line 876 %x0D ; Carriage return 877 S = *B ; optional blank space 878 RS = 1*B ; required blank space 880 The slice-selector consists of three optional decimal integers 881 separated by colons. 883 Semantics 885 The slice-selector was inspired by the slice operator of ECMAScript 4 886 (ES4), which was deprecated in 2014, and that of Python. 888 Informal Introduction 890 This section is non-normative. 892 Array indexing is a way of selecting a particular element of an array 893 using a 0-based index. For example, the expression [0] selects the 894 first element of a non-empty array. 896 Negative indices index from the end of an array. For example, the 897 expression [-2] selects the last but one element of an array with at 898 least two elements. 900 Array slicing is inspired by the behaviour of the 901 Array.prototype.slice method of the JavaScript language as defined by 902 the ECMA-262 standard [ECMA-262], with the addition of the step 903 parameter, which is inspired by the Python slice expression. 905 The array slice expression [start:end:step] selects elements at 906 indices starting at start, incrementing by step, and ending with end 907 (which is itself excluded). So, for example, the expression [1:3] 908 (where step defaults to 1) selects elements with indices 1 and 2 (in 909 that order) whereas [1:5:2] selects elements with indices 1 and 3. 911 When step is negative, elements are selected in reverse order. Thus, 912 for example, [5:1:-2] selects elements with indices 5 and 3, in that 913 order and [::-1] selects all the elements of an array in reverse 914 order. 916 When step is 0, no elements are selected. (This is the one case that 917 differs from the behaviour of Python, which raises an error in this 918 case.) 920 The following section specifies the behaviour fully, without 921 depending on JavaScript or Python behaviour. 923 Detailed Semantics 925 An array selector is either an array slice or an array index, which 926 is defined in terms of an array slice. 928 A slice expression selects a subset of the elements of the input 929 array, in the same order as the array or the reverse order, depending 930 on the sign of the step parameter. It selects no nodes from a node 931 that is not an array. 933 A slice is defined by the two slice parameters, start and end, and an 934 iteration delta, step. Each of these parameters is optional. len is 935 the length of the input array. 937 The default value for step is 1. The default values for start and 938 end depend on the sign of step, as follows: 940 +===========+=========+==========+ 941 | Condition | start | end | 942 +===========+=========+==========+ 943 | step >= 0 | 0 | len | 944 +-----------+---------+----------+ 945 | step < 0 | len - 1 | -len - 1 | 946 +-----------+---------+----------+ 948 Table 9: Default array slice 949 start and end values 951 Slice expression parameters start and end are not directly usable as 952 slice bounds and must first be normalized. Normalization for this 953 purpose is defined as: 955 FUNCTION Normalize(i, len): 956 IF i >= 0 THEN 957 RETURN i 958 ELSE 959 RETURN len + i 960 END IF 962 The result of the array indexing expression [i] applied to an array 963 of length len is defined to be the result of the array slicing 964 expression [i:Normalize(i, len)+1:1]. 966 Slice expression parameters start and end are used to derive slice 967 bounds lower and upper. The direction of the iteration, defined by 968 the sign of step, determines which of the parameters is the lower 969 bound and which is the upper bound: 971 FUNCTION Bounds(start, end, step, len): 972 n_start = Normalize(start, len) 973 n_end = Normalize(end, len) 975 IF step >= 0 THEN 976 lower = MIN(MAX(n_start, 0), len) 977 upper = MIN(MAX(n_end, 0), len) 978 ELSE 979 upper = MIN(MAX(n_start, -1), len-1) 980 lower = MIN(MAX(n_end, -1), len-1) 981 END IF 983 RETURN (lower, upper) 985 The slice expression selects elements with indices between the lower 986 and upper bounds. In the following pseudocode, the a(i) construct 987 expresses the 0-based indexing operation on the underlying array. 989 IF step > 0 THEN 991 i = lower 992 WHILE i < upper: 993 SELECT a(i) 994 i = i + step 995 END WHILE 997 ELSE if step < 0 THEN 999 i = upper 1000 WHILE lower < i: 1001 SELECT a(i) 1002 i = i + step 1003 END WHILE 1005 END IF 1007 When step = 0, no elements are selected and the result array is 1008 empty. 1010 To be valid, the slice expression parameters MUST be in the I-JSON 1011 range of exact values, see Section 3.1. 1013 Examples 1015 JSON document: 1017 ["a", "b", "c", "d", "e", "f", "g"] 1019 Queries: 1021 +===========+========+========+==========+ 1022 | Query | Result | Result | Comment | 1023 | | | Paths | | 1024 +===========+========+========+==========+ 1025 | $[1:3] | "b" | $[1] | Slice | 1026 | | "c" | $[2] | with | 1027 | | | | default | 1028 | | | | step | 1029 +-----------+--------+--------+----------+ 1030 | $[1:5:2] | "b" | $[1] | Slice | 1031 | | "d" | $[3] | with | 1032 | | | | step 2 | 1033 +-----------+--------+--------+----------+ 1034 | $[5:1:-2] | "f" | $[5] | Slice | 1035 | | "d" | $[3] | with | 1036 | | | | negative | 1037 | | | | step | 1038 +-----------+--------+--------+----------+ 1039 | $[::-1] | "g" | $[6] | Slice in | 1040 | | "f" | $[5] | reverse | 1041 | | "e" | $[4] | order | 1042 | | "d" | $[3] | | 1043 | | "c" | $[2] | | 1044 | | "b" | $[1] | | 1045 | | "a" | $[0] | | 1046 +-----------+--------+--------+----------+ 1048 Table 10: Array slice selector examples 1050 3.5.7. Descendant Selector 1052 Syntax 1054 The descendant selector starts with a double dot .. and can be 1055 followed by an object member name (similar to the dot-selector), by 1056 an index-selector acting on objects or arrays, or by a wildcard. 1058 descendant-selector = ".." ( dot-member-name / ; .. 1059 index-selector / ; ..[] 1060 index-wild-selector / ; ..[*] 1061 "*" ; ..* 1062 ) 1064 Semantics 1066 The descendant-selector selects certain descendants of a node: 1068 * the .. form (and the ..[] form where is a 1069 quoted-member-name) selects those descendants of the node that are 1070 member values of an object with the given member name. 1072 * the ..[] where is an element-index selects those 1073 descendants of the node that are array elements with the given 1074 index. 1076 * the ..[*] and ..* forms select all the descendants of the node. 1078 In the resultant nodelist: 1080 * nodes occur before their children, and 1082 * nodes of an array occur in array order. 1084 Children of an object may occur in any order, since JSON objects are 1085 unordered. 1087 Examples 1089 JSON document: 1091 { 1092 "o": {"j": 1, "k": 2}, 1093 "a": [5, 3, [{"j": 4}]] 1094 } 1096 Queries: 1098 +========+====================+===================+=============+ 1099 | Query | Result | Result Paths | Comment | 1100 +========+====================+===================+=============+ 1101 | $..j | 1 | $['o']['j'] | Object | 1102 | | 4 | $['a'][2][0]['j'] | values | 1103 +--------+--------------------+-------------------+-------------+ 1104 | $..j | 4 | $['a'][2][0]['j'] | Alternative | 1105 | | 1 | $['o']['j'] | result | 1106 +--------+--------------------+-------------------+-------------+ 1107 | $..[0] | 5 | $['a'][0] | Array | 1108 | | {"j": 4} | $['a'][2][0] | values | 1109 +--------+--------------------+-------------------+-------------+ 1110 | $..[0] | {"j": 4} | $['a'][2][0] | Alternative | 1111 | | 5 | $['a'][0] | result | 1112 +--------+--------------------+-------------------+-------------+ 1113 | $..[*] | {"j": 1, "k" : 2} | $['o'] | All values | 1114 | | [5, 3, [{"j": 4}]] | $['a'] | | 1115 | | 1 | $['o']['j'] | | 1116 | | 2 | $['o']['k'] | | 1117 | | 5 | $['a'][0] | | 1118 | | 3 | $['a'][1] | | 1119 | | [{"j": 4}] | $['a'][2] | | 1120 | | {"j": 4} | $['a'][2][0] | | 1121 | | 4 | $['a'][2][0]['j'] | | 1122 +--------+--------------------+-------------------+-------------+ 1123 | $..* | [5, 3, [{"j": 4}]] | $['a'] | All values | 1124 | | {"j": 1, "k" : 2} | $['o'] | | 1125 | | 2 | $['o']['k'] | | 1126 | | 1 | $['o']['j'] | | 1127 | | 5 | $['a'][0] | | 1128 | | 3 | $['a'][1] | | 1129 | | [{"j": 4}] | $['a'][2] | | 1130 | | {"j": 4} | $['a'][2][0] | | 1131 | | 4 | $['a'][2][0]['j'] | | 1132 +--------+--------------------+-------------------+-------------+ 1134 Table 11: Descendant selector examples 1136 Note: The ordering of the results for the $..[*] and $..* examples 1137 above is not guaranteed, except that: 1139 * {"j": 1, "k": 2} must appear before 1 and 2, 1141 * [5, 3, [{"j": 4}]] must appear before 5, 3, and [{"j": 4}], 1143 * 5 must appear before 3 which must appear before [{"j": 4}], 1145 * [{"j": 4}] must appear before {"j": 4}, and 1146 * {"j": 4} must appear before 4. 1148 3.5.8. Filter Selector 1150 Syntax 1152 The filter selector has the form [?]. It works via iterating 1153 over structured values, i.e. arrays and objects. 1155 filter-selector = "[" S filter S "]" 1156 filter = "?" S boolean-expr 1158 During iteration process each array element or object member is 1159 visited and its value -- accessible via symbol @ -- or one of its 1160 descendants -- uniquely defined by a relative path -- is tested 1161 against a boolean expression boolean-expr. 1163 The current item is selected if and only if the result is true. 1165 boolean-expr = logical-or-expr 1166 logical-or-expr = logical-and-expr *(S "||" S logical-and-expr) 1167 ; disjunction 1168 ; binds less tightly than conjunction 1169 logical-and-expr = basic-expr *(S "&&" S basic-expr) ; conjunction 1170 ; binds more tightly than disjunction 1172 basic-expr = exist-expr / 1173 paren-expr / 1174 relation-expr 1175 exist-expr = [neg-op S] singular-path ; path existence or non-existence 1177 Paths in filter expressions are Singular Paths, each of which selects 1178 at most one node. 1180 singular-path = rel-singular-path / abs-singular-path 1181 rel-singular-path = "@" *(S (dot-selector / index-selector)) 1182 abs-singular-path = root-selector *(S (dot-selector / index-selector)) 1184 Parentheses can be used with boolean-expr for grouping. So filter 1185 selection syntax in the original proposal [?()] is naturally 1186 contained in the current lean syntax [?] as a special case. 1188 paren-expr = [neg-op S] "(" S boolean-expr S ")" ; parenthesized expression 1189 neg-op = "!" ; not operator 1191 relation-expr = comp-expr / ; comparison test 1192 regex-expr ; regular expression test 1194 Comparisons are restricted to Singular Path values and primitive 1195 values (such as number, string, true, false, null). 1197 Comparisons with complex values will fail, i.e. no selection occurs. 1199 Data types are not implicitly converted in comparisons. So "13 == 1200 '13'" selects no node. 1202 A member or element value by itself in a Boolean context is 1203 interpreted as false only if it does not exist. Otherwise it is 1204 interpreted as true. To be more specific about the actual value, 1205 explicit comparisons are necessary. This existence test -- as an 1206 exception to the general rule -- also works with structured values. 1208 comp-expr = comparable S comp-op S comparable 1209 comparable = number / string-literal / ; primitive ... 1210 true / false / null / ; values only 1211 singular-path ; Singular Path value 1212 comp-op = "==" / "!=" / ; comparison ... 1213 "<" / ">" / ; operators 1214 "<=" / ">=" 1216 Alphabetic characters in ABNF are case-insensitive, so "e" can be 1217 either "e" or "E". 1219 true, false, and null are lower-case only (case-sensitive). 1221 number = int [ frac ] [ exp ] ; decimal number 1222 frac = "." 1*DIGIT ; decimal fraction 1223 exp = "e" [ "-" / "+" ] 1*DIGIT ; decimal exponent 1224 true = %x74.72.75.65 ; true 1225 false = %x66.61.6c.73.65 ; false 1226 null = %x6e.75.6c.6c ; null 1228 Regular expression tests can be applied to JSON string values 1229 (Section 7 of [RFC8259]) only (on the left-hand side of =~); they 1230 yield false otherwise. 1232 The syntax of regular expressions in the string-literals on the 1233 right-hand side of =~ is as defined in 1234 [I-D.draft-bormann-jsonpath-iregexp]. 1236 regex-expr = (singular-path / string-literal) S regex-op S regex 1237 regex-op = "=~" ; regular expression match 1238 regex = string-literal ; I-Regexp 1239 The following table lists filter expression operators in order of 1240 precedence from highest (binds most tightly) to lowest (binds least 1241 tightly). 1243 +============+===========+===========+ 1244 | Precedence | Operator | Syntax | 1245 | | type | | 1246 +============+===========+===========+ 1247 | 5 | Grouping | (...) | 1248 +------------+-----------+-----------+ 1249 | 4 | Logical | ! | 1250 | | NOT | | 1251 +------------+-----------+-----------+ 1252 | 3 | Relations | == != | 1253 | | | < <= > >= | 1254 | | | =~ | 1255 +------------+-----------+-----------+ 1256 | 2 | Logical | && | 1257 | | AND | | 1258 +------------+-----------+-----------+ 1259 | 1 | Logical | || | 1260 | | OR | | 1261 +------------+-----------+-----------+ 1263 Table 12: Filter expression 1264 operator precedence 1266 Semantics 1268 The filter-selector works with arrays and objects exclusively. Its 1269 result is a list of _zero_, _one_, _multiple_ or _all_ of their array 1270 elements or member values, respectively. Applied to other value 1271 types, it will select nothing. 1273 A relative path, beginning with @, refers to the current array 1274 element or member value as the filter selector iterates over the 1275 array or object. 1277 Comparisons using one of the operators <, <=, >, and >= are between 1278 numeric values only. Using these operators to compare other types of 1279 values produces a "false" comparison result. 1281 The semantics of regular expressions are as defined in 1282 [I-D.draft-bormann-jsonpath-iregexp]. 1284 Examples 1286 JSON document: 1288 { 1289 "a": [3, 5, 1, 2, 4, 6, {"b": "ij"}, {"b": "ik"}], 1290 "o": {"p": 1, "q": 2, "r": 3, "s": 5, "t": {"u": 6}} 1291 } 1293 Queries: 1295 +=============+=============+=============+=============+ 1296 | Query | Result | Result | Comment | 1297 | | | Paths | | 1298 +=============+=============+=============+=============+ 1299 | $.a[?@>3.5] | 5 | $['a'][1] | Array value | 1300 | | 4 | $['a'][4] | comparison | 1301 | | 6 | $['a'][5] | | 1302 +-------------+-------------+-------------+-------------+ 1303 | $.a[?@.b] | {"b": "ij"} | $['a'][6] | Array value | 1304 | | {"b": "ik"} | $['a'][7] | existence | 1305 +-------------+-------------+-------------+-------------+ 1306 | $.a[?@<2 || | 1 | $['a'][2] | Array value | 1307 | @.b == | {"b": "ik"} | $['a'][7] | logical OR | 1308 | "ik"] | | | | 1309 +-------------+-------------+-------------+-------------+ 1310 | $.a[?@.b =~ | {"b": "ij"} | $['a'][6] | Array value | 1311 | "i.*"] | {"b": "ik"} | $['a'][7] | regular | 1312 | | | | expression | 1313 +-------------+-------------+-------------+-------------+ 1314 | $.o[?@>1 && | 2 | $['o']['q'] | Object | 1315 | @<4] | 3 | $['o']['r'] | value | 1316 | | | | logical AND | 1317 +-------------+-------------+-------------+-------------+ 1318 | $.o[?@>1 && | 3 | $['o']['r'] | Alternative | 1319 | @<4] | 2 | $['o']['q'] | result | 1320 +-------------+-------------+-------------+-------------+ 1321 | $.o[?@.u || | {"u": 6} | $['o']['t'] | Object | 1322 | @.x] | | | value | 1323 | | | | logical OR | 1324 +-------------+-------------+-------------+-------------+ 1326 Table 13: Filter selector examples 1328 3.5.9. List Selector 1330 The list selector allows combining member names, array indices, and 1331 slices in a single selector. 1333 Note: The list selector was called "union selector" in 1334 [JSONPath-orig], as it was intended to solve use cases addressed by 1335 the union selector in XPath. However, the term "union" has the 1336 connotation of a set operation that involves merging input sets while 1337 avoiding duplicates, so the concept was renamed into "list selector". 1339 Syntax 1341 The list selector is syntactically related to the index-selector and 1342 the slice-selector. It contains two or more entries, separated by 1343 commas. 1345 list-selector = "[" S list-entry 1*(S "," S list-entry) S "]" 1347 list-entry = ( quoted-member-name / 1348 element-index / 1349 slice-index / 1350 filter 1351 ) 1353 Semantics 1355 A list selector selects the nodes that are selected by at least one 1356 of the selector entries in the list and yields the concatenation of 1357 the lists (in the order of the selector entries) of nodes selected by 1358 the selector entries. Note that any node selected in more than one 1359 of the selector entries is kept as many times in the node list. 1361 To be valid, integer values in the element-index and slice-index 1362 components MUST be in the I-JSON range of exact values, see 1363 Section 3.1. 1365 Examples 1367 JSON document: 1369 ["a", "b", "c", "d", "e", "f", "g"] 1371 Queries: 1373 +========+========+========+============+ 1374 | Query | Result | Result | Comment | 1375 | | | Paths | | 1376 +========+========+========+============+ 1377 | $[0, | "a" | $[0] | Indices | 1378 | 3] | "d" | $[3] | | 1379 +--------+--------+--------+------------+ 1380 | $[0:2, | "a" | $[0] | Slice and | 1381 | 5] | "b" | $[1] | index | 1382 | | "f" | $[5] | | 1383 +--------+--------+--------+------------+ 1384 | $[0, | "a" | $[0] | Duplicated | 1385 | 0] | "a" | $[0] | entries | 1386 +--------+--------+--------+------------+ 1388 Table 14: List selector examples 1390 3.6. Semantics of null 1392 Note that JSON null is treated the same as any other JSON value: it 1393 is not taken to mean "undefined" or "missing". 1395 Examples 1397 JSON document: 1399 {"a": null, "b": [null], "c": [{}], "null": 1} 1401 Queries: 1403 +===================+========+===========+====================+ 1404 | Query | Result | Result | Comment | 1405 | | | Paths | | 1406 +===================+========+===========+====================+ 1407 | $.a | null | $['a'] | Object value | 1408 +-------------------+--------+-----------+--------------------+ 1409 | $.a[0] | | | null used as array | 1410 +-------------------+--------+-----------+--------------------+ 1411 | $.a.d | | | null used as | 1412 | | | | object | 1413 +-------------------+--------+-----------+--------------------+ 1414 | $.b[0] | null | $['b'][0] | Array value | 1415 +-------------------+--------+-----------+--------------------+ 1416 | $.b[*] | null | $['b'][0] | Array value | 1417 +-------------------+--------+-----------+--------------------+ 1418 | $.b[?@] | null | $['b'][0] | Existence | 1419 +-------------------+--------+-----------+--------------------+ 1420 | $.b[?@==null] | null | $['b'][0] | Comparison | 1421 +-------------------+--------+-----------+--------------------+ 1422 | $.c[?(@.d==null)] | | | Comparison with | 1423 | | | | "missing" value | 1424 +-------------------+--------+-----------+--------------------+ 1425 | $.null | 1 | $['null'] | Not JSON null at | 1426 | | | | all, just a string | 1427 | | | | as object key | 1428 +-------------------+--------+-----------+--------------------+ 1430 Table 15: Examples involving (or not involving) null 1432 3.7. Normalized Paths 1434 A Normalized Path is a JSONPath with restricted syntax that 1435 identifies a node by providing a query that results in exactly that 1436 node. For example, the JSONPath expression $.book[?(@.price<10)] 1437 could select two values with Normalized Paths $['book'][3] and 1438 $['book'][5]. For a given JSON document, there is a one to one 1439 correspondence between the document's nodes and the Normalized Paths 1440 that identify these nodes. 1442 A JSONPath implementation may output Normalized Paths instead of, or 1443 in addition to, the values identified by these paths. 1445 Since bracket notation is more general than dot notation, it is used 1446 to construct Normalized Paths. Single quotes are used to delimit 1447 string member names. This reduces the number of characters that need 1448 escaping when Normalized Paths appear as strings (which are delimited 1449 with double quotes) in JSON documents. 1451 The syntax of Normalized Paths is restricted so that there is one and 1452 only one way of representing any given Normalized Path. Putting this 1453 another way, for any two distinct Normalized Paths, a JSON document 1454 exists that will yield distinct results when the Normalized Paths are 1455 applied to it. 1457 Certain characters are escaped, in one and only one way; all other 1458 characters are unescaped. 1460 Normalized Paths are Singular Paths. Not all Singular Paths are 1461 Normalized Paths: $[-3], for example, is a Singular Path, but not a 1462 Normalized Path. 1464 normalized-path = root-selector *(normal-index-selector) 1465 normal-index-selector = "[" (normal-quoted-member-name / normal-element-index) "]" 1466 normal-quoted-member-name = %x27 *normal-single-quoted %x27 ; 'string' 1467 normal-single-quoted = normal-unescaped / 1468 ESC normal-escapable 1469 normal-unescaped = %x20-26 / ; omit control codes 1470 %x28-5B / ; omit ' 1471 %x5D-10FFFF ; omit \ 1472 normal-escapable = ( %x62 / %x66 / %x6E / %x72 / %x74 / ; \b \f \n \r \t 1473 ; b / ; BS backspace U+0008 1474 ; t / ; HT horizontal tab U+0009 1475 ; n / ; LF line feed U+000A 1476 ; f / ; FF form feed U+000C 1477 ; r / ; CR carriage return U+000D 1478 "'" / ; ' apostrophe U+0027 1479 "\" / ; \ backslash (reverse solidus) U+005C 1480 (%x75 normal-hexchar) ; certain values u00XX U+00XX 1481 ) 1482 normal-hexchar = "0" "0" 1483 ( 1484 ("0" %x30-37) / ; "00"-"07" 1485 ("0" %x62) / ; "0b" ; omit U+0008-U+000A 1486 ("0" %x65-66) / ; "0e"-"0f" ; omit U+000C-U+000D 1487 ("1" normal-HEXDIG) 1488 ) 1489 normal-HEXDIG = DIGIT / %x61-66 ; "0"-"9", "a"-"f" 1490 normal-element-index = "0" / (DIGIT1 *DIGIT) ; non-negative decimal integer 1492 Examples 1494 +============+=================+==================+ 1495 | Path | Normalized Path | Comment | 1496 +============+=================+==================+ 1497 | $.a | $['a'] | Object value | 1498 +------------+-----------------+------------------+ 1499 | $[1] | $[1] | Array index | 1500 +------------+-----------------+------------------+ 1501 | $.a.b[1:2] | $['a']['b'][1] | Nested structure | 1502 +------------+-----------------+------------------+ 1504 Table 16: Normalized Path examples 1506 4. IANA Considerations 1508 4.1. Registration of Media Type application/jsonpath 1510 IANA is requested to register the following media type [RFC6838]: 1512 Type name: application 1514 Subtype name: jsonpath 1516 Required parameters: N/A 1518 Optional parameters: N/A 1520 Encoding considerations: binary (UTF-8) 1522 Security considerations: See the Security Considerations section of 1523 RFCXXXX. 1525 Interoperability considerations: N/A 1527 Published specification: RFCXXXX 1529 Applications that use this media type: Applications that need to 1530 convey queries in JSON data 1532 Fragment identifier considerations: N/A 1534 Additional information: Deprecated alias names for this type: N/A 1536 Magic number(s): N/A 1538 File extension(s): N/A 1539 Macintosh file type code(s): N/A 1541 Person & email address to contact for further information: 1542 iesg@ietf.org 1544 Intended usage: COMMON 1546 Restrictions on usage: N/A 1548 Author: JSONPath WG 1550 Change controller: IESG 1552 Provisional registration? (standards tree only): no 1554 5. Security Considerations 1556 Security considerations for JSONPath can stem from 1558 * attack vectors on JSONPath implementations, and 1560 * the way JSONPath is used in security-relevant mechanisms. 1562 5.1. Attack vectors on JSONPath Implementations 1564 Historically, JSONPath has often been implemented by feeding parts of 1565 the query to an underlying programming language engine, e.g., 1566 JavaScript. This approach is well known to lead to injection attacks 1567 and would require perfect input validation to prevent these attacks 1568 (see Section 12 of [RFC8259] for similar considerations for JSON 1569 itself). Instead, JSONPath implementations need to implement the 1570 entire syntax of the query without relying on the parsers of 1571 programming language engines. 1573 Attacks on availability may attempt to trigger unusually expensive 1574 runtime performance exhibited by certain implementations in certain 1575 cases. (See Section 10 of [RFC8949] for issues in hash-table 1576 implementations, and Section 8 of 1577 [I-D.draft-bormann-jsonpath-iregexp] for performance issues in 1578 regular expression implementations.) Implementers need to be aware 1579 that good average performance is not sufficient as long as an 1580 attacker can choose to submit specially crafted JSONPath queries that 1581 trigger surprisingly high, possibly exponential, CPU usage. 1583 5.2. Attacks on Security Mechanisms that Employ JSONPath 1585 Where JSONPath is used as a part of a security mechanism, attackers 1586 can attempt to evoke unexpected behavior, or take advantage of 1587 differences in behavior between JSONPath implementations. 1589 This also applies to underlying technologies such as UTF-8 (see 1590 Section 10 of [RFC3629]), the Unicode character set, and JSON. A 1591 characteristic of JSON that can lead to varying results is the fact 1592 that JSON objects are unordered; therefore, the order in which 1593 results of a JSONPath query reflect the presence of JSON object 1594 members can vary with implementations. 1596 6. References 1598 6.1. Normative References 1600 [I-D.draft-bormann-jsonpath-iregexp] 1601 Bormann, C. and T. Bray, "I-Regexp: An Interoperable 1602 Regexp Format", Work in Progress, Internet-Draft, draft- 1603 bormann-jsonpath-iregexp-03, 7 March 2022, 1604 . 1607 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1608 Requirement Levels", BCP 14, RFC 2119, 1609 DOI 10.17487/RFC2119, March 1997, 1610 . 1612 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1613 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1614 2003, . 1616 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1617 Specifications: ABNF", STD 68, RFC 5234, 1618 DOI 10.17487/RFC5234, January 2008, 1619 . 1621 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1622 Specifications and Registration Procedures", BCP 13, 1623 RFC 6838, DOI 10.17487/RFC6838, January 2013, 1624 . 1626 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, 1627 DOI 10.17487/RFC7493, March 2015, 1628 . 1630 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1631 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1632 May 2017, . 1634 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1635 Interchange Format", STD 90, RFC 8259, 1636 DOI 10.17487/RFC8259, December 2017, 1637 . 1639 6.2. Informative References 1641 [E4X] ISO, "Information technology — ECMAScript for XML (E4X) 1642 specification", ISO/IEC 22537:2006 , 2006. 1644 [ECMA-262] Ecma International, "ECMAScript Language Specification, 1645 Standard ECMA-262, Third Edition", December 1999, 1646 . 1650 [JSONPath-orig] 1651 Gössner, S., "JSONPath — XPath for JSON", 21 February 1652 2007, . 1654 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 1655 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 1656 DOI 10.17487/RFC6901, April 2013, 1657 . 1659 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 1660 Representation (CBOR)", STD 94, RFC 8949, 1661 DOI 10.17487/RFC8949, December 2020, 1662 . 1664 [SLICE] "Slice notation", n.d., 1665 . 1667 [XPath] Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., 1668 Kay, M., Robie, J., and J. Simeon, "XML Path Language 1669 (XPath) 2.0 (Second Edition)", World Wide Web Consortium 1670 Recommendation REC-xpath20-20101214, 14 December 2010, 1671 . 1673 Appendix A. Inspired by XPath 1675 This appendix is informative. 1677 At the time JSONPath was invented, XML was noted for the availability 1678 of powerful tools to analyse, transform and selectively extract data 1679 from XML documents. [XPath] is one of these tools. 1681 In 2007, the need for something solving the same class of problems 1682 for the emerging JSON community became apparent, specifically for: 1684 * Finding data interactively and extracting them out of [RFC8259] 1685 JSON values without special scripting. 1687 * Specifying the relevant parts of the JSON data in a request by a 1688 client, so the server can reduce the amount of data in its 1689 response, minimizing bandwidth usage. 1691 (Note that XPath has evolved since 2007, and recent versions even 1692 nominally support operating inside JSON values. This appendix only 1693 discusses the more widely used version of XPath that was available in 1694 2007.) 1696 JSONPath picks up the overall feeling of XPath, but maps the concepts 1697 to syntax (and partially semantics) that would be familiar to someone 1698 using JSON in a dynamic language. 1700 E.g., in popular dynamic programming languages such as JavaScript, 1701 Python and PHP, the semantics of the XPath expression 1703 /store/book[1]/title 1705 can be realized in the expression 1707 x.store.book[0].title 1709 or, in bracket notation, 1711 x['store']['book'][0]['title'] 1713 with the variable x holding the argument. 1715 The JSONPath language was designed to: 1717 * be naturally based on those language characteristics; 1719 * cover only the most essential parts of XPath 1.0; 1721 * be lightweight in code size and memory consumption; 1723 * be runtime efficient. 1725 A.1. JSONPath and XPath 1727 JSONPath expressions apply to JSON values in the same way as XPath 1728 expressions are used in combination with an XML document. JSONPath 1729 uses $ to refer to the root node of the argument, similar to XPath's 1730 / at the front. 1732 JSONPath expressions move further down the hierarchy using _dot 1733 notation_ ($.store.book[0].title) or the _bracket notation_ 1734 ($['store']['book'][0]['title']), a lightweight/limited, and a more 1735 heavyweight syntax replacing XPath's / within query expressions. 1737 Both JSONPath and XPath use * for a wildcard. The descendant 1738 operator .., borrowed from [E4X], is similar to XPath's //. The array 1739 slicing construct [start:end:step] is unique to JSONPath, inspired by 1740 [SLICE] from ECMASCRIPT 4. 1742 Filter expressions are supported via the syntax ?() as 1743 in 1745 $.store.book[?(@.price < 10)].title 1747 Table 17 extends Table 1 by providing a comparison with similar XPath 1748 concepts. 1750 +==========+==================+===================================+ 1751 | XPath | JSONPath | Description | 1752 +==========+==================+===================================+ 1753 | / | $ | the root XML element | 1754 +----------+------------------+-----------------------------------+ 1755 | . | @ | the current XML element | 1756 +----------+------------------+-----------------------------------+ 1757 | / | . or [] | child operator | 1758 +----------+------------------+-----------------------------------+ 1759 | .. | n/a | parent operator | 1760 +----------+------------------+-----------------------------------+ 1761 | // | .. | descendants (JSONPath borrows | 1762 | | | this syntax from E4X) | 1763 +----------+------------------+-----------------------------------+ 1764 | * | * | wildcard: All XML elements | 1765 | | | regardless of their names | 1766 +----------+------------------+-----------------------------------+ 1767 | @ | n/a | attribute access: JSON values do | 1768 | | | not have attributes | 1769 +----------+------------------+-----------------------------------+ 1770 | [] | [] | subscript operator used to | 1771 | | | iterate over XML element | 1772 | | | collections and for predicates | 1773 +----------+------------------+-----------------------------------+ 1774 | | | [,] | Union operator (results in a | 1775 | | | combination of node sets); called | 1776 | | | list operator in JSONPath, allows | 1777 | | | combining member names, array | 1778 | | | indices, and slices | 1779 +----------+------------------+-----------------------------------+ 1780 | n/a | [start:end:step] | array slice operator borrowed | 1781 | | | from ES4 | 1782 +----------+------------------+-----------------------------------+ 1783 | [] | ?() | applies a filter (script) | 1784 | | | expression | 1785 +----------+------------------+-----------------------------------+ 1786 | seamless | n/a | expression engine | 1787 +----------+------------------+-----------------------------------+ 1788 | () | n/a | grouping | 1789 +----------+------------------+-----------------------------------+ 1791 Table 17: XPath syntax compared to JSONPath 1793 For further illustration, Table 18 shows some XPath expressions and 1794 their JSONPath equivalents. 1796 +======================+========================+===================+ 1797 | XPath | JSONPath | Result | 1798 +======================+========================+===================+ 1799 | /store/book/author | $.store.book[*].author | the authors of | 1800 | | | all books in | 1801 | | | the store | 1802 +----------------------+------------------------+-------------------+ 1803 | //author | $..author | all authors | 1804 +----------------------+------------------------+-------------------+ 1805 | /store/* | $.store.* | all things in | 1806 | | | store, which | 1807 | | | are some books | 1808 | | | and a red | 1809 | | | bicycle | 1810 +----------------------+------------------------+-------------------+ 1811 | /store//price | $.store..price | the prices of | 1812 | | | everything in | 1813 | | | the store | 1814 +----------------------+------------------------+-------------------+ 1815 | //book[3] | $..book[2] | the third book | 1816 +----------------------+------------------------+-------------------+ 1817 | //book[last()] | $..book[-1] | the last book | 1818 | | | in order | 1819 +----------------------+------------------------+-------------------+ 1820 | //book[position()<3] | $..book[0,1] | the first two | 1821 | | $..book[:2] | books | 1822 +----------------------+------------------------+-------------------+ 1823 | //book[isbn] | $..book[?(@.isbn)] | filter all | 1824 | | | books with isbn | 1825 | | | number | 1826 +----------------------+------------------------+-------------------+ 1827 | //book[price<10] | $..book[?(@.price<10)] | filter all | 1828 | | | books cheaper | 1829 | | | than 10 | 1830 +----------------------+------------------------+-------------------+ 1831 | //* | $..* | all elements in | 1832 | | | XML document; | 1833 | | | all member | 1834 | | | values and | 1835 | | | array elements | 1836 | | | contained in | 1837 | | | input value | 1838 +----------------------+------------------------+-------------------+ 1840 Table 18: Example XPath expressions and their JSONPath equivalents 1842 XPath has a lot more functionality (location paths in unabbreviated 1843 syntax, operators and functions) than listed in this comparison. 1844 Moreover, there are significant differences in how the subscript 1845 operator works in XPath and JSONPath: 1847 * Square brackets in XPath expressions always operate on the _node 1848 set_ resulting from the previous path fragment. Indices always 1849 start at 1. 1851 * With JSONPath, square brackets operate on the _object_ or _array_ 1852 addressed by the previous path fragment. Array indices always 1853 start at 0. 1855 Appendix B. JSON Pointer 1857 This appendix is informative. 1859 JSONPath is not intended as a replacement for, but as a more powerful 1860 companion to, JSON Pointer [RFC6901]. The purposes of the two 1861 standards are different. 1863 JSON Pointer is for identifying a single value within a JSON document 1864 whose structure is known. 1866 JSONPath can identify a single value within a JSON document, for 1867 example by using a Normalized Path. But JSONPath is also a query 1868 syntax that can be used to search for and extract multiple values 1869 from JSON documents whose structure is known only in a general way. 1871 A Normalized JSONPath can be converted into a JSON Pointer by 1872 converting the syntax, without knowledge of any JSON document. The 1873 inverse is not generally true: a numeric path component in a JSON 1874 Pointer may identify a member of a JSON object or may index an array. 1875 For conversion to a JSONPath query, knowledge of the structure of the 1876 JSON document is needed to distinguish these cases. 1878 Acknowledgements 1880 This specification is based on Stefan Gössner's original online 1881 article defining JSONPath [JSONPath-orig]. 1883 The books example was taken from http://coli.lili.uni- 1884 bielefeld.de/~andreas/Seminare/sommer02/books.xml -- a dead link now. 1886 Contributors 1887 Marko Mikulicic 1888 InfluxData, Inc. 1889 Pisa 1890 Italy 1891 Email: mmikulicic@gmail.com 1893 Edward Surov 1894 TheSoul Publishing Ltd. 1895 Limassol 1896 Cyprus 1897 Email: esurov.tsp@gmail.com 1899 Authors' Addresses 1901 Stefan Gössner (editor) 1902 Fachhochschule Dortmund 1903 Sonnenstraße 96 1904 D-44139 Dortmund 1905 Germany 1906 Email: stefan.goessner@fh-dortmund.de 1908 Glyn Normington (editor) 1909 Winchester 1910 United Kingdom 1911 Email: glyn.normington@gmail.com 1913 Carsten Bormann (editor) 1914 Universität Bremen TZI 1915 Postfach 330440 1916 D-28359 Bremen 1917 Germany 1918 Phone: +49-421-218-63921 1919 Email: cabo@tzi.org