idnits 2.17.1 draft-normington-jsonpath-00.txt: -(8): 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 7 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (7 December 2020) is 1235 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 212 -- Looks like a reference, but probably isn't: '1' on line 214 -- Looks like a reference, but probably isn't: '2' on line 364 -- Looks like a reference, but probably isn't: '3' on line 364 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JSONPath WG G. Normington, Ed. 3 Internet-Draft VMware, Inc. 4 Intended status: Standards Track E. Surov, Ed. 5 Expires: 10 June 2021 TheSoul Publishing Ltd. 6 M. Mikulicic 7 VMware, Inc. 8 S. Gössner 9 Fachhochschule Dortmund 10 7 December 2020 12 JavaScript Object Notation (JSON) Path 13 draft-normington-jsonpath-00 15 Abstract 17 JSONPath defines a string syntax for identifying values within a 18 JavaScript Object Notation (JSON) document. 20 Note 22 *This document is a work in progress and has not yet been published 23 as an Internet Draft* (which needs to be fixed soon). 25 Contributing 27 This document picks up the popular JSONPath specification dated 28 2007-02-21 and provides a normative definition for it. In its 29 current state, it is a strawman document showing what needs to be 30 covered. 32 Comments and issues can be directed at the github repository _insert 33 repo here_ as well as (for the time when the more permanent home is 34 being decided) at the dispatch@ietf.org mailing list. 36 Status of This Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at https://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on 10 June 2021. 53 Copyright Notice 55 Copyright (c) 2020 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 60 license-info) in effect on the date of publication of this document. 61 Please review these documents carefully, as they describe your rights 62 and restrictions with respect to this document. Code Components 63 extracted from this document must include Simplified BSD License text 64 as described in Section 4.e of the Trust Legal Provisions and are 65 provided without warranty as described in the Simplified BSD License. 67 Table of Contents 69 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 70 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 71 1.2. Inspired by XPath . . . . . . . . . . . . . . . . . . . . 4 72 1.3. Overview of JSONPath Expressions . . . . . . . . . . . . 5 73 2. JSONPath Examples . . . . . . . . . . . . . . . . . . . . . . 7 74 3. JSONPath Syntax and Semantics . . . . . . . . . . . . . . . . 10 75 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 10 76 3.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 10 77 3.3. Implementation . . . . . . . . . . . . . . . . . . . . . 10 78 3.4. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 11 79 3.5. Semantics . . . . . . . . . . . . . . . . . . . . . . . . 11 80 3.6. Selectors . . . . . . . . . . . . . . . . . . . . . . . . 12 81 3.6.1. Dot Child Selector . . . . . . . . . . . . . . . . . 12 82 3.6.2. Union Selector . . . . . . . . . . . . . . . . . . . 13 83 3.6.2.1. Syntax . . . . . . . . . . . . . . . . . . . . . 13 84 3.6.2.2. Semantics . . . . . . . . . . . . . . . . . . . . 13 85 3.6.2.3. Child . . . . . . . . . . . . . . . . . . . . . . 13 86 3.6.2.4. Array Selector . . . . . . . . . . . . . . . . . 15 87 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 88 5. Security Considerations . . . . . . . . . . . . . . . . . . . 19 89 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 90 6.1. Normative References . . . . . . . . . . . . . . . . . . 19 91 6.2. Informative References . . . . . . . . . . . . . . . . . 19 92 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 20 93 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 20 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 96 1. Introduction 98 This document picks up the popular JSONPath specification dated 99 2007-02-21 [JSONPath-orig] and provides a normative definition for 100 it. In its current state, it is a strawman document showing what 101 needs to be covered. 103 JSON is defined by [RFC8259]. 105 JSONPath is not intended as a replacement, but as a more powerful 106 companion, to JSON Pointer [RFC6901]. [insert reference to section 107 where the relationship is detailed. The purposes of the two syntaxes 108 are different. Pointer is for isolating a single location within a 109 document. Path is a query syntax that can also be used to pull 110 multiple locations.] 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. 128 Data Item: A structure complying to the generic data model of JSON, 129 i.e., composed of containers such as arrays and maps (JSON 130 objects), and of atomic data such as null, true, false, numbers, 131 and text strings. 133 Object: Used in its generic sense, e.g., for programming language 134 objects. When a JSON Object as defined in [RFC8259] is meant, we 135 specifically say JSON Object. 137 Query: Short name for JSONPath expression. 139 Argument: Short name for the JSON data item a JSONPath expression is 140 applied to. 142 Output Path: A simple form of JSONPath expression that identifies a 143 Position by providing a query that results in exactly that 144 position. Similar to, but syntactically different from, a JSON 145 Pointer [RFC6901]. 147 Position: A JSON data item identical to or nested within the JSON 148 data item to which the query is applied to, expressed either by 149 the value of that data item or by providing a JSONPath Output 150 Path. 152 1.2. Inspired by XPath 154 A frequently emphasized advantage of XML is the availability of 155 powerful tools to analyse, transform and selectively extract data 156 from XML documents. [XPath] is one of these tools. 158 In 2007, the need for something solving the same class of problems 159 for the emerging JSON community became apparent, specifically for: 161 * Finding data interactively and extracting them out of [RFC8259] 162 data items without special scripting. 164 * Specifying the relevant parts of the JSON data in a request by a 165 client, so the server can reduce the amount of data in its 166 response, minimizing bandwidth usage. 168 So what does such a tool look like for JSON? When defining a 169 JSONPath, how should expressions look? 171 The XPath expression 173 /store/book[1]/title 175 looks like 177 x.store.book[0].title 179 or 181 x['store']['book'][0]['title'] 183 in popular programming languages such as JavaScript, Python and PHP, 184 with a variable x holding the JSON data item. Here we observe that 185 such languages already have a fundamentally XPath-like feature built 186 in. 188 The JSONPath tool in question should: 190 * be naturally based on those language characteristics. 192 * cover only essential parts of XPath 1.0. 194 * be lightweight in code size and memory consumption. 196 * be runtime efficient. 198 1.3. Overview of JSONPath Expressions 200 JSONPath expressions always apply to a JSON data item in the same way 201 as XPath expressions are used in combination with an XML document. 202 Since a JSON data item is usually anonymous and doesn't necessarily 203 have a "root member object", JSONPath used the abstract name "$" to 204 refer to the top level object of the data item. 206 JSONPath expressions can use the _dot-notation_ 208 $.store.book[0].title 210 or the _bracket-notation_ 212 $['store']['book'][0]['title'] 214 for paths input to a JSONPath processor. [1] Where a JSONPath 215 processor uses JSONPath expressions as output paths, these will 216 always be converted to the more general _bracket-notation_. [2] 217 Bracket notation is more general than dot notation and can serve as a 218 canonical form when a JSONPath processor uses JSONPath expressions as 219 output paths. 221 JSONPath allows the wildcard symbol "*" for member names and array 222 indices. It borrows the descendant operator ".." from [E4X] and the 223 array slice syntax proposal "[start:end:step]" [SLICE] from 224 ECMASCRIPT 4. 226 JSONPath was originally designed to employ an _underlying scripting 227 language_ for computing expressions. The present specification 228 defines a simple expression language that is independent from any 229 scripting language in use on the platform. 231 JSONPath can use expressions, written in parentheses: "()", as 232 an alternative to explicit names or indices as in: 234 $.store.book[(@.length-1)].title 236 The symbol "@" is used for the current object. Filter expressions 237 are supported via the syntax "?()" as in 238 $.store.book[?(@.price < 10)].title 240 Here is a complete overview and a side by side comparison of the 241 JSONPath syntax elements with their XPath counterparts. 243 +=======+==================+=====================================+ 244 | XPath | JSONPath | Description | 245 +=======+==================+=====================================+ 246 | / | $ | the root object/element | 247 +-------+------------------+-------------------------------------+ 248 | . | @ | the current object/element | 249 +-------+------------------+-------------------------------------+ 250 | / | "." or "[]" | child operator | 251 +-------+------------------+-------------------------------------+ 252 | .. | n/a | parent operator | 253 +-------+------------------+-------------------------------------+ 254 | // | .. | nested descendants (JSONPath | 255 | | | borrows this syntax from E4X) | 256 +-------+------------------+-------------------------------------+ 257 | * | * | wildcard: All objects/elements | 258 | | | regardless of their names | 259 +-------+------------------+-------------------------------------+ 260 | @ | n/a | attribute access: JSON data items | 261 | | | do not have attributes | 262 +-------+------------------+-------------------------------------+ 263 | [] | [] | subscript operator: XPath uses it | 264 | | | to iterate over element collections | 265 | | | and for predicates; native array | 266 | | | indexing as in JavaScript here | 267 +-------+------------------+-------------------------------------+ 268 | | | [,] | Union operator in XPath (results in | 269 | | | a combination of node sets); | 270 | | | JSONPath allows alternate names or | 271 | | | array indices as a set | 272 +-------+------------------+-------------------------------------+ 273 | n/a | [start:end:step] | array slice operator borrowed from | 274 | | | ES4 | 275 +-------+------------------+-------------------------------------+ 276 | [] | ?() | applies a filter (script) | 277 | | | expression | 278 +-------+------------------+-------------------------------------+ 279 | n/a | () | expression engine | 280 +-------+------------------+-------------------------------------+ 281 | () | n/a | grouping in Xpath | 282 +-------+------------------+-------------------------------------+ 284 Table 1: Overview over JSONPath, comparing to XPath 286 XPath has a lot more to offer (location paths in unabbreviated 287 syntax, operators and functions) than listed here. Moreover there is 288 a significant difference how the subscript operator works in Xpath 289 and JSONPath: 291 * Square brackets in XPath expressions always operate on the _node 292 set_ resulting from the previous path fragment. Indices always 293 start at 1. 295 * With JSONPath, square brackets operate on the _object_ or _array_ 296 addressed by the previous path fragment. Array indices always 297 start at 0. 299 2. JSONPath Examples 301 This section provides some more examples for JSONPath expressions. 302 The examples are based on a simple JSON data item patterned after a 303 typical XML example representing a bookstore (that also has 304 bicycles): 306 { "store": { 307 "book": [ 308 { "category": "reference", 309 "author": "Nigel Rees", 310 "title": "Sayings of the Century", 311 "price": 8.95 312 }, 313 { "category": "fiction", 314 "author": "Evelyn Waugh", 315 "title": "Sword of Honour", 316 "price": 12.99 317 }, 318 { "category": "fiction", 319 "author": "Herman Melville", 320 "title": "Moby Dick", 321 "isbn": "0-553-21311-3", 322 "price": 8.99 323 }, 324 { "category": "fiction", 325 "author": "J. R. R. Tolkien", 326 "title": "The Lord of the Rings", 327 "isbn": "0-395-19395-8", 328 "price": 22.99 329 } 330 ], 331 "bicycle": { 332 "color": "red", 333 "price": 19.95 334 } 335 } 336 } 338 Figure 1: Example JSON data item 340 The examples in Table 2 use the expression mechanism to obtain the 341 number of items in an array, to test for the presence of a map 342 member, and to perform numeric comparisons of map member values with 343 a constant. 345 +======================+=========================+==================+ 346 | XPath | JSONPath | Result | 347 +======================+=========================+==================+ 348 | /store/book/author | $.store.book[*].author | the authors of | 349 | | | all books in | 350 | | | the store | 351 +----------------------+-------------------------+------------------+ 352 | //author | $..author | all authors | 353 +----------------------+-------------------------+------------------+ 354 | /store/* | $.store.* | all things in | 355 | | | store, which | 356 | | | are some books | 357 | | | and a red | 358 | | | bicycle | 359 +----------------------+-------------------------+------------------+ 360 | /store//price | $.store..price | the prices of | 361 | | | everything in | 362 | | | the store | 363 +----------------------+-------------------------+------------------+ 364 | //book[3] | $..book[2] | the third book | 365 +----------------------+-------------------------+------------------+ 366 | //book[last()] | "$..book[(@.length-1)]" | the last book | 367 | | "$..book[-1]" | in order | 368 +----------------------+-------------------------+------------------+ 369 | //book[position()<3] | "$..book[0,1]" | the first two | 370 | | "$..book[:2]" | books | 371 +----------------------+-------------------------+------------------+ 372 | //book[isbn] | $..book[?(@.isbn)] | filter all | 373 | | | books with | 374 | | | isbn number | 375 +----------------------+-------------------------+------------------+ 376 | //book[price<10] | $..book[?(@.price<10)] | filter all | 377 | | | books cheaper | 378 | | | than 10 | 379 +----------------------+-------------------------+------------------+ 380 | //* | $..* | all elements | 381 | | | in XML | 382 | | | document; all | 383 | | | members of | 384 | | | JSON data item | 385 +----------------------+-------------------------+------------------+ 387 Table 2: Example JSONPath expressions applied to the example JSON 388 data item 390 3. JSONPath Syntax and Semantics 392 3.1. Overview 394 A JSONPath is a string which selects zero or more nodes of a piece of 395 JSON. A valid JSONPath conforms to the ABNF syntax defined by this 396 document. 398 A JSONPath MUST be encoded using UTF-8. To parse a JSONPath 399 according to the grammar in this document, its UTF-8 form SHOULD 400 first be decoded into Unicode code points as described in [RFC3629]. 402 3.2. Terminology 404 A JSON value is logically a tree of nodes. 406 Each node holds a JSON value (as defined by [RFC8259]) of one of the 407 types object, array, number, string, or one of the literals "true", 408 "false", or "null". The type of the JSON value held by a node is 409 sometimes referred to as the type of the node. 411 3.3. Implementation 413 An implementation of this specification, from now on referred to 414 simply as "an implementation", SHOULD takes two inputs, a JSONPath 415 and a JSON value, and produce a possibly empty list of nodes of the 416 JSON value which are selected by the JSONPath or an error (but not 417 both). 419 If no node is selected and no error has occurred, an implementation 420 MUST return an empty list of nodes. 422 Syntax errors in the JSONPath SHOULD be detected before selection is 423 attempted since these errors do not depend on the JSON value. 424 Therefore, an implementation SHOULD take a JSONPath and produce an 425 optional syntax error and then, if and only if an error was not 426 produced, SHOULD take a JSON value and produce a list of nodes or an 427 error (but not both). 429 Alternatively, an implementation MAY take a JSONPath and a JSON value 430 and produce a list of nodes or an optional error (but not both). 432 For any implementation, if a syntactically invalid JSONPath is 433 provided, the implementation MUST return an error. 435 If a syntactially invalid JSON value is provided, any implementation 436 SHOULD return an error. 438 3.4. Syntax 440 Syntactically, a JSONPath consists of a root selector ("$"), which 441 selects the root node of a JSON value, followed by a possibly empty 442 sequence of _selectors_. 444 json-path = root-selector *selector 445 root-selector = %x24 ; $ selects document root node 447 The syntax and semantics of each selector is defined below. 449 3.5. Semantics 451 The root selector "$" not only selects the root node of the input 452 document, but it also produces as output a list consisting of one 453 node: the input document. 455 A selector may select zero or more nodes for further processing. A 456 syntactically valid selector MUST NOT produce errors. This means 457 that some operations which might be considered erroneous, such as 458 indexing beyond the end of an array, simply result in fewer nodes 459 being selected. 461 But a selector doesn't just act on a single node: each selector acts 462 on a list of nodes and produces a list of nodes, as follows. 464 After the root selector, the remainder of the JSONPath is processed 465 by passing lists of nodes from one selector to the next ending up 466 with a list of nodes which is the result of applying the JSONPath to 467 the input JSON value. 469 Each selector acts on its input list of nodes as follows. For each 470 node in the list, the selector selects zero or more nodes, each of 471 which is a descendant of the node or the node itself. The output 472 list of nodes of a selector is the concatenation of the lists of 473 selected nodes for each input node. 475 A specific, non-normative example will make this clearer. Suppose 476 the input document is: "{"a":[{"b":0},{"b":1},{"c":2}]}". As we will 477 see later, the JSONPath "$.a[*].b" selects the following list of 478 nodes: "0", "1". Let's walk through this in detail. 480 The JSONPath consists of "$" followed by three selectors: ".a", 481 "[*]", and ".b". 483 Firstly, "$" selects the root node which is the input document. So 484 the result is a list consisting of just the root node. 486 Next, ".a" selects from any input node of type object and selects any 487 value of the input node corresponding to the key ""a"". The result 488 is again a list of one node: "[{"b":0},{"b":1},{"c":2}]". 490 Next, "[*]" selects from any input node which is an array and selects 491 all the elements of the input node. The result is a list of three 492 nodes: "{"b":0}", "{"b":1}", and "{"c":2}". 494 Finally, ".b" selects from any input node of type object with a key 495 "b" and selects the value of the input node corresponding to that 496 key. The result is a list containing "0", "1". This is the 497 concatenation of three lists, two of length one containing "0", "1", 498 respectively, and one of length zero. 500 As a consequence of this approach, if any of the selectors selects no 501 nodes, then the whole JSONPath selects no nodes. 503 In what follows, the semantics of each selector are defined for each 504 type of node. 506 3.6. Selectors 508 3.6.1. Dot Child Selector 510 Syntax 512 A dot child selector has a key known as a dot child name or a single 513 asterisk ("*"). 515 A dot child name corresponds to a name in a JSON object. 517 selector = dot-child ; see below for alternatives 518 dot-child = %x2E dot-child-name / ; . 519 %x2E %x2A ; .* 520 dot-child-name = 1*( 521 %x2D / ; - 522 DIGIT / 523 ALPHA / 524 %x5F / ; _ 525 %x80-10FFFF ; any non-ASCII Unicode character 526 ) 527 DIGIT = %x30-39 ; 0-9 528 ALPHA = %x41-5A / %x61-7A ; A-Z / a-z 530 More general child names, such as the empty string, are supported by 531 "Union Child" (Section 3.6.2.3). 533 Note that the "dot-child-name" rule follows the philosophy of JSON 534 strings and is allowed to contain bit sequences that cannot encode 535 Unicode characters (a single unpaired UTF-16 surrogate, for example). 536 The behaviour of an implementation is undefined for child names which 537 do not encode Unicode characters. 539 Semantics 541 A dot child name which is not a single asterisk ("*") is considered 542 to have a key. It selects the value corresponding to the key from 543 any object node. It selects no nodes from a node which is not an 544 object. 546 The key of a dot child name is the sequence of Unicode characters 547 contained in that name. 549 A dot child name consisting of a single asterisk is a wild card. It 550 selects all the values of any object node. It also selects all the 551 elements of any array node. It selects no nodes from number, string, 552 or literal nodes. 554 3.6.2. Union Selector 556 3.6.2.1. Syntax 558 A union selector consists of one or more union elements. 560 selector =/ union 561 union = %x5B ws union-elements ws %x5D ; [...] 562 ws = *%x20 ; zero or more spaces 563 union-elements = union-element / 564 union-element ws %x2C ws union-elements 565 ; ,-separated list 567 3.6.2.2. Semantics 569 A union selects any node which is selected by at least one of the 570 union selectors and selects the concatenation of the lists (in the 571 order of the selectors) of nodes selected by the union elements. 573 3.6.2.3. Child 575 Syntax 577 A child is a quoted string. 579 union-element = child ; see below for more alternatives 580 child = %x22 *double-quoted %x22 / ; "string" 581 %x27 *single-quoted %x27 ; 'string' 583 double-quoted = dq-unescaped / 584 escape ( 585 %x22 / ; " quotation mark U+0022 586 %x2F / ; / solidus U+002F 587 %x5C / ; \ reverse solidus U+005C 588 %x62 / ; b backspace U+0008 589 %x66 / ; f form feed U+000C 590 %x6E / ; n line feed U+000A 591 %x72 / ; r carriage return U+000D 592 %x74 / ; t tab U+0009 593 %x75 4HEXDIG ) ; uXXXX U+XXXX 595 dq-unescaped = %x20-21 / %x23-5B / %x5D-10FFFF 597 single-quoted = sq-unescaped / 598 escape ( 599 %x27 / ; ' apostrophe U+0027 600 %x2F / ; / solidus U+002F 601 %x5C / ; \ reverse solidus U+005C 602 %x62 / ; b backspace U+0008 603 %x66 / ; f form feed U+000C 604 %x6E / ; n line feed U+000A 605 %x72 / ; r carriage return U+000D 606 %x74 / ; t tab U+0009 607 %x75 4HEXDIG ) ; uXXXX U+XXXX 609 sq-unescaped = %x20-26 / %x28-5B / %x5D-10FFFF 611 escape = %x5C ; \ 613 HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" 614 ; case insensitive hex digit 616 Notes: 1. double-quoted strings follow JSON in [RFC8259]. Single- 617 quoted strings follow an analogous pattern. 2. "HEXDIG" includes A-F 618 and a-f. 620 Semantics 622 If the child is a quoted string, the string MUST be converted to a 623 key by removing the surrounding quotes and replacing each escape 624 sequence with its equivalent Unicode character, as in the table 625 below: 627 +=================+===================+ 628 | Escape Sequence | Unicode Character | 629 +=================+===================+ 630 | %x5C %x22 | U+0022 | 631 +-----------------+-------------------+ 632 | %x5C %x27 | U+0027 | 633 +-----------------+-------------------+ 634 | %x5C %x2F | U+002F | 635 +-----------------+-------------------+ 636 | %x5C %x5C | U+005C | 637 +-----------------+-------------------+ 638 | %x5C %x62 | U+0008 | 639 +-----------------+-------------------+ 640 | %x5C %x66 | U+000C | 641 +-----------------+-------------------+ 642 | %x5C %x6E | U+000A | 643 +-----------------+-------------------+ 644 | %x5C %x72 | U+000D | 645 +-----------------+-------------------+ 646 | %x5C %x74 | U+0009 | 647 +-----------------+-------------------+ 648 | %x5C uXXXX | U+XXXX | 649 +-----------------+-------------------+ 651 Table 3: Escape Sequence Replacements 653 The child selects the value corresponding to the key from any object 654 node with the key as a name. It selects no nodes from a node which 655 is not an object. 657 3.6.2.4. Array Selector 659 Syntax 661 An array selector selects zero or more elements of an array node. An 662 array selector takes the form of an index, which selects at most one 663 element, or a slice, which selects zero or more elements. 665 union-element =/ array-index / array-slice 667 An array index is an integer (in base 10). 669 array-index = integer 671 integer = ["-"] ("0" / (DIGIT1 *DIGIT)) 672 ; optional - followed by 0 or 673 ; sequence of digits with no leading zero 674 DIGIT1 = %x31-39 ; non-zero digit 675 Note: the syntax does not allow integers with leading zeros such as 676 "01" and "-01". 678 An array slice consists of three optional integers (in base 10) 679 separated by colons. 681 array-slice = [ start ] ws ":" ws [ end ] 682 [ ws ":" ws [ step ] ] 683 start = integer 684 end = integer 685 step = integer 687 Note: the array slices ":" and "::" are both syntactically valid, as 688 are ":2:2", "2::2", and "2:4:". 690 Semantics 692 Informal Introduction 694 This section is non-normative. 696 Array indexing is a way of selecting a particular element of an array 697 using a 0-based index. For example, the expression "[0]" selects the 698 first element of a non-empty array. 700 Negative indices index from the end of an array. For example, the 701 expression "[-2]" selects the last but one element of an array with 702 at least two elements. 704 Array slicing is inspired by the behaviour of the 705 "Array.prototype.slice" method of the JavaScript language as defined 706 by the ECMA-262 standard [ECMA-262], with the addition of the "step" 707 parameter, which is inspired by the Python slice expression. 709 The array slice expression "[start:end:step]" selects elements at 710 indices starting at "start", incrementing by "step", and ending with 711 "end" (which is itself excluded). So, for example, the expression 712 "[1:3]" (where "step" defaults to "1") selects elements with indices 713 "1" and "2" (in that order) whereas "[1:5:2]" selects elements with 714 indices "1" and "3". 716 When "step" is negative, elements are selected in reverse order. 717 Thus, for example, "[5:1:-2]" selects elements with indices "5" and 718 "3", in that order and "[::-1]" selects all the elements of an array 719 in reverse order. 721 When "step" is "0", no elements are selected. This is the one case 722 which differs from the behaviour of Python, which raises an error in 723 this case. 725 The following section specifies the behaviour fully, without 726 depending on JavaScript or Python behaviour. 728 Detailed Semantics 730 An array selector is either an array slice or an array index, which 731 is defined in terms of an array slice. 733 A slice expression selects a subset of the elements of the input 734 array, in the same order as the array or the reverse order, depending 735 on the sign of the "step" parameter. It selects no nodes from a node 736 which is not an array. 738 A slice is defined by the two slice parameters, "start" and "end", 739 and an iteration delta, "step". Each of these parameters is 740 optional. "len" is the length of the input array. 742 The default value for "step" is "1". The default values for "start" 743 and "end" depend on the sign of "step", as follows: 745 +===========+=========+==========+ 746 | Condition | start | end | 747 +===========+=========+==========+ 748 | step >= 0 | 0 | len | 749 +-----------+---------+----------+ 750 | step < 0 | len - 1 | -len - 1 | 751 +-----------+---------+----------+ 753 Table 4: Default array slice 754 start and end values 756 Slice expression parameters "start" and "end" are not directly usable 757 as slice bounds and must first be normalized. Normalization is 758 defined as: 760 FUNCTION Normalize(i): 761 IF i >= 0 THEN 762 RETURN i 763 ELSE 764 RETURN len + i 765 END IF 767 The result of the array indexing expression "[i]" is defined to be 768 the result of the array slicing expression "[i:Normalize(i)+1:1]". 770 Slice expression parameters "start" and "end" are used to derive 771 slice bounds "lower" and "upper". The direction of the iteration, 772 defined by the sign of "step", determines which of the parameters is 773 the lower bound and which is the upper bound: 775 FUNCTION Bounds(start, end, step, len): 776 n_start = Normalize(start) 777 n_end = Normalize(end) 779 IF step >= 0 THEN 780 lower = MIN(MAX(n_start, 0), len) 781 upper = MIN(MAX(n_end, 0), len) 782 ELSE 783 upper = MIN(MAX(n_start, -1), len-1) 784 lower = MIN(MAX(n_end, -1), len-1) 785 END IF 787 RETURN (lower, upper) 789 The slice expression selects elements with indices between the lower 790 and upper bounds. In the following pseudocode, the "a(i)" construct 791 expresses the 0-based indexing operation on the underlying array. 793 IF step > 0 THEN 795 i = lower 796 WHILE i < upper: 797 SELECT a(i) 798 i = i + step 799 END WHILE 801 ELSE if step < 0 THEN 803 i = upper 804 WHILE lower < i: 805 SELECT a(i) 806 i = i + step 807 END WHILE 809 END IF 811 When "step = 0", no elements are selected and the result array is 812 empty. 814 An implementation MUST raise an error if any of the slice expression 815 parameters does not fit in the implementation's representation of an 816 integer. If a successfully parsed slice expression is evaluated 817 against an array whose size doesn't fit in the implementation's 818 representation of an integer, the implementation MUST raise an error. 820 4. IANA Considerations 822 TBD: Define a media type for JSON Path expressions. 824 5. Security Considerations 826 This section gives security considerations, as required by [RFC3552]. 828 6. References 830 6.1. Normative References 832 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 833 Requirement Levels", BCP 14, RFC 2119, 834 DOI 10.17487/RFC2119, March 1997, 835 . 837 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 838 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 839 2003, . 841 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 842 Specifications: ABNF", STD 68, RFC 5234, 843 DOI 10.17487/RFC5234, January 2008, 844 . 846 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 847 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 848 May 2017, . 850 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 851 Interchange Format", STD 90, RFC 8259, 852 DOI 10.17487/RFC8259, December 2017, 853 . 855 6.2. Informative References 857 [E4X] ISO, "Information technology — ECMAScript for XML (E4X) 858 specification", ISO/IEC 22537:2006 , 2006. 860 [ECMA-262] Ecma International, "ECMAScript Language Specification, 861 Standard ECMA-262, Third Edition", December 1999, 862 . 866 [JSONPath-orig] 867 Gössner, S., "JSONPath – XPath for JSON", 21 February 868 2007, . 870 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 871 Text on Security Considerations", BCP 72, RFC 3552, 872 DOI 10.17487/RFC3552, July 2003, 873 . 875 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 876 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 877 DOI 10.17487/RFC6901, April 2013, 878 . 880 [SLICE] "Slice notation", n.d., 881 . 883 [XPath] Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., 884 Kay, M., Robie, J., and J. Simeon, "XML Path Language 885 (XPath) 2.0 (Second Edition)", World Wide Web Consortium 886 Recommendation REC-xpath20-20101214, 14 December 2010, 887 . 889 Acknowledgements 891 This specification is based on Stefan Gössner's original online 892 article defining JSONPath [JSONPath-orig]. 894 The books example was taken from http://coli.lili.uni- 895 bielefeld.de/~andreas/Seminare/sommer02/books.xml -- a dead link now. 897 Contributors 899 Carsten Bormann 900 Universität Bremen TZI 901 Postfach 330440 902 D-28359 Bremen 903 Germany 905 Phone: +49-421-218-63921 906 Email: cabo@tzi.org 908 Authors' Addresses 910 Glyn Normington (editor) 911 VMware, Inc. 912 Winchester 913 United Kingdom 915 Email: glyn.normington@gmail.com 917 Edward Surov (editor) 918 TheSoul Publishing Ltd. 919 Limassol 920 Cyprus 922 Email: esurov.tsp@gmail.com 924 Marko Mikulicic 925 VMware, Inc. 926 Pisa 927 Italy 929 Email: mmikulicic@gmail.com 931 Stefan Gössner 932 Fachhochschule Dortmund 933 Sonnenstraße 96 934 D-44139 Dortmund 935 Germany 937 Email: stefan.goessner@fh-dortmund.de