idnits 2.17.1 draft-bhutton-relative-json-pointer-00.txt: 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: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There is 1 instance of too long lines in the document, the longest one being 12 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 (December 8, 2020) is 1228 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force G. Luff 3 Internet-Draft 4 Intended status: Informational H. Andrews, Ed. 5 Expires: June 11, 2021 6 B. Hutton, Ed. 7 December 8, 2020 9 Relative JSON Pointers 10 draft-bhutton-relative-json-pointer-00 12 Abstract 14 JSON Pointer is a syntax for specifying locations in a JSON document, 15 starting from the document root. This document defines an extension 16 to the JSON Pointer syntax, allowing relative locations from within 17 the document. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on June 11, 2021. 36 Copyright Notice 38 Copyright (c) 2020 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 2 55 3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 56 4. Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 5. JSON String Representation . . . . . . . . . . . . . . . . . 4 58 5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 4 59 6. Non-use in URI Fragment Identifiers . . . . . . . . . . . . . 5 60 7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 5 61 8. Relationship to JSON Pointer . . . . . . . . . . . . . . . . 5 62 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 63 10. Security Considerations . . . . . . . . . . . . . . . . . . . 6 64 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 65 11.1. Normative References . . . . . . . . . . . . . . . . . . 6 66 11.2. Informative References . . . . . . . . . . . . . . . . . 6 67 Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 7 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7 70 1. Introduction 72 JSON Pointer (RFC 6901 [RFC6901]) is a syntax for specifying 73 locations in a JSON document, starting from the document root. This 74 document defines a related syntax allowing identification of relative 75 locations from within the document. 77 2. Conventions and Terminology 79 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 80 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 81 document are to be interpreted as described in RFC 2119 [RFC2119]. 83 3. Syntax 85 A Relative JSON Pointer is a Unicode string in UTF-8 encoding (see 86 RFC 8259, Section 8 [RFC8259]), comprising a non-negative integer, 87 followed by either a '#' (%x23) character or a JSON Pointer (RFC 6901 88 [RFC6901]). 90 The separation between the integer prefix and the JSON Pointer will 91 always be unambiguous, because a JSON Pointer must be either zero- 92 length or start with a '/' (%x2F). Similarly, a JSON Pointer will 93 never be ambiguous with the '#'. 95 The ABNF syntax of a Relative JSON Pointer is: 97 relative-json-pointer = non-negative-integer [index-manipulation] 98 relative-json-pointer =/ non-negative-integer "#" 99 index-manipulation = ("+" / "-") non-negative-integer 100 non-negative-integer = %x30 / %x31-39 *( %x30-39 ) 101 ; "0", or digits without a leading "0" 103 where follows the production defined in RFC 6901, 104 Section 3 [RFC6901] ("Syntax"). 106 4. Evaluation 108 Evaluation of a Relative JSON Pointer begins with a reference to a 109 value within a JSON document, and completes with either a value 110 within that document, a string corresponding to an object member, or 111 integer value representing an array index. 113 Evaluation begins by processing the non-negative-integer prefix. 114 This can be found by taking the longest continuous sequence of 115 decimal digits available, starting from the beginning of the string, 116 taking the decimal numerical value. If this value is more than zero, 117 then the following steps are repeated that number of times: 119 If the current referenced value is the root of the document, then 120 evaluation fails (see below). 122 If the referenced value is an item within an array, then the new 123 referenced value is that array. 125 If the referenced value is an object member within an object, then 126 the new referenced value is that object. 128 If the next character is a plus ("+") or minus ("-"), followed by 129 another continuous sequence of decimal digits, the following steps 130 are taken using the decimal numeric value of that plus or minus sign 131 and decimal sequence: 133 If the current referenced value is not an item of an array, then 134 evaluation fails (see below). 136 If the referenced value is an item of an array, then the new 137 referenced value is the item of the array indexed by adding the 138 decimal value (which may be negative), to the index of the current 139 referenced value. 141 If the remainder of the Relative JSON Pointer is a JSON Pointer, then 142 evaluation proceeds as per RFC 6901, Section 5 [RFC6901] with the 143 modification that the initial reference being used is the reference 144 currently being held (which may not be root of the document). 146 Otherwise (when the remainder of the Relative JSON Pointer is the 147 character '#'), the final result is determined as follows: 149 If the current referenced value is the root of the document, then 150 evaluation fails (see below). 152 If the referenced value is an item within an array, then the final 153 evaluation result is the value's index position within the array. 155 If the referenced value is an object member within an object, then 156 the new referenced value is the corresponding member name. 158 5. JSON String Representation 160 The concerns surrounding JSON String representation of a Relative 161 JSON Pointer are identical to those laid out in RFC 6901, Section 5 162 [RFC6901]. 164 5.1. Examples 166 For example, given the JSON document: 168 { 169 "foo": ["bar", "baz"], 170 "highly": { 171 "nested": { 172 "objects": true 173 } 174 } 175 } 177 Starting from the value "baz" (inside "foo"), the following JSON 178 strings evaluate to the accompanying values: 180 "0" "baz" 181 "1/0" "bar" 182 "0-1" "bar" 183 "2/highly/nested/objects" true 184 "0#" 1 185 "0-1#" 0 186 "1#" "foo" 188 Starting from the value {"objects":true} (corresponding to the member 189 key "nested"), the following JSON strings evaluate to the 190 accompanying values: 192 "0/objects" true 193 "1/nested/objects" true 194 "2/foo/0" "bar" 195 "0#" "nested" 196 "1#" "highly" 198 6. Non-use in URI Fragment Identifiers 200 Unlike a JSON Pointer, a Relative JSON Pointer can not be used in a 201 URI fragment identifier. Such fragments specify exact positions 202 within a document, and therefore Relative JSON Pointers are not 203 suitable. 205 7. Error Handling 207 In the event of an error condition, evaluation of the JSON Pointer 208 fails to complete. 210 Evaluation may fail due to invalid syntax, or referencing a non- 211 existent value. This specification does not define how errors are 212 handled. An application of JSON Relative Pointer SHOULD specify the 213 impact and handling of each type of error. 215 8. Relationship to JSON Pointer 217 Relative JSON Pointers are intended as a companion to JSON Pointers. 218 Applications MUST specify the use of each syntax separately. 219 Defining either JSON Pointer or Relative JSON Pointer as an 220 acceptable syntax does not imply that the other syntax is also 221 acceptable. 223 9. Acknowledgements 225 The language and structure of this specification are based heavily on 226 [RFC6901], sometimes quoting it outright. 228 This draft remains primarily as written and published by Geraint 229 Luff, with only minor subsequent alterations under new editorship. 231 10. Security Considerations 233 Evaluation of a given Relative JSON Pointer is not guaranteed to 234 reference an actual JSON value. Applications using Relative JSON 235 Pointer should anticipate this situation by defining how a pointer 236 that does not resolve ought to be handled. 238 As part of processing, a composite data structure may be assembled 239 from multiple JSON documents (in part or in full). In such cases, 240 applications SHOULD ensure that a Relative JSON Pointer does not 241 evaluate to a value outside the document for which is was written. 243 Note that JSON pointers can contain the NUL (Unicode U+0000) 244 character. Care is needed not to misinterpret this character in 245 programming languages that use NUL to mark the end of a string. 247 11. References 249 11.1. Normative References 251 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 252 Requirement Levels", BCP 14, RFC 2119, 253 DOI 10.17487/RFC2119, March 1997, 254 . 256 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 257 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 258 DOI 10.17487/RFC6901, April 2013, 259 . 261 11.2. Informative References 263 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 264 Interchange Format", STD 90, RFC 8259, 265 DOI 10.17487/RFC8259, December 2017, 266 . 268 Appendix A. ChangeLog 270 [[CREF1: This section to be removed before leaving Internet-Draft 271 status.]] 273 draft-bhutton-relative-json-pointer-00 275 * Add array forward and backward index manipulation 277 draft-handrews-relative-json-pointer-02 279 * Update to the latest JSON RFC 281 draft-handrews-relative-json-pointer-01 283 * The initial number is "non-negative", not "positive" 285 draft-handrews-relative-json-pointer-00 287 * Revived draft with identical wording and structure. 289 * Clarified how to use alongside JSON Pointer. 291 draft-luff-relative-json-pointer-00 293 * Initial draft. 295 Authors' Addresses 297 Geraint Luff 298 Cambridge 299 UK 301 EMail: luffgd@gmail.com 303 Henry Andrews (editor) 305 EMail: andrews_henry@yahoo.com 307 Ben Hutton (editor) 309 EMail: ben@jsonschema.dev 310 URI: https://jsonschema.dev