idnits 2.17.1 draft-handrews-relative-json-pointer-02.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.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 16, 2019) is 1677 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 1 error (**), 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: March 19, 2020 September 16, 2019 7 Relative JSON Pointers 8 draft-handrews-relative-json-pointer-02 10 Abstract 12 JSON Pointer is a syntax for specifying locations in a JSON document, 13 starting from the document root. This document defines an extension 14 to the JSON Pointer syntax, allowing relative locations from within 15 the document. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on March 19, 2020. 34 Copyright Notice 36 Copyright (c) 2019 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 2 53 3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 54 4. Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 5. JSON String Representation . . . . . . . . . . . . . . . . . 4 56 5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 4 57 6. Non-use in URI Fragment Identifiers . . . . . . . . . . . . . 5 58 7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 5 59 8. Relationship to JSON Pointer . . . . . . . . . . . . . . . . 5 60 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 5 61 10. Security Considerations . . . . . . . . . . . . . . . . . . . 5 62 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 63 11.1. Normative References . . . . . . . . . . . . . . . . . . 6 64 11.2. Informative References . . . . . . . . . . . . . . . . . 6 65 Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 7 66 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7 68 1. Introduction 70 JSON Pointer (RFC 6901 [RFC6901]) is a syntax for specifying 71 locations in a JSON document, starting from the document root. This 72 document defines a related syntax allowing identification of relative 73 locations from within the document. 75 2. Conventions and Terminology 77 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 78 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 79 document are to be interpreted as described in RFC 2119 [RFC2119]. 81 3. Syntax 83 A Relative JSON Pointer is a Unicode string in UTF-8 encoding (see 84 RFC 8259, Section 8 [RFC8259]), comprising a non-negative integer, 85 followed by either a '#' (%x23) character or a JSON Pointer (RFC 6901 86 [RFC6901]). 88 The separation between the integer prefix and the JSON Pointer will 89 always be unambiguous, because a JSON Pointer must be either zero- 90 length or start with a '/' (%x2F). Similarly, a JSON Pointer will 91 never be ambiguous with the '#'. 93 The ABNF syntax of a Relative JSON Pointer is: 95 relative-json-pointer = non-negative-integer <json-pointer> 96 relative-json-pointer =/ non-negative-integer "#" 97 non-negative-integer = %x30 / %x31-39 *( %x30-39 ) 98 ; "0", or digits without a leading "0" 100 where follows the production defined in RFC 6901, 101 Section 3 [RFC6901] ("Syntax"). 103 4. Evaluation 105 Evaluation of a Relative JSON Pointer begins with a reference to a 106 value within a JSON document, and completes with either a value 107 within that document, a string corresponding to an object member, or 108 integer value representing an array index. 110 Evaluation begins by processing the non-negative-integer prefix. 111 This can be found by taking the longest continuous sequence of 112 decimal digits available, starting from the beginning of the string, 113 taking the decimal numerical value. If this value is more than zero, 114 then the following steps are repeated that number of times: 116 If the current referenced value is the root of the document, then 117 evaluation fails (see below). 119 If the referenced value is an item within an array, then the new 120 referenced value is that array. 122 If the referenced value is an object member within an object, then 123 the new referenced value is that object. 125 If the remainder of the Relative JSON Pointer is a JSON Pointer, then 126 evaluation proceeds as per RFC 6901, Section 4 [RFC6901] 127 ("Evaluation"), with the modification that the initial reference 128 being used is the reference currently being held (which may not be 129 root of the document). 131 Otherwise (when the remainder of the Relative JSON Pointer is the 132 character '#'), the final result is determined as follows: 134 If the current referenced value is the root of the document, then 135 evaluation fails (see below). 137 If the referenced value is an item within an array, then the final 138 evaluation result is the value's index position within the array. 140 If the referenced value is an object member within an object, then 141 the new referenced value is the corresponding member name. 143 5. JSON String Representation 145 The concerns surrounding JSON String representation of a Relative 146 JSON Pointer are identical to those laid out in RFC 6901, Section 5 147 [RFC6901]. 149 5.1. Examples 151 For example, given the JSON document: 153 { 154 "foo": ["bar", "baz"], 155 "highly": { 156 "nested": { 157 "objects": true 158 } 159 } 160 } 162 Starting from the value "baz" (inside "foo"), the following JSON 163 strings evaluate to the accompanying values: 165 "0" "baz" 166 "1/0" "bar" 167 "2/highly/nested/objects" true 168 "0#" 1 169 "1#" "foo" 171 Starting from the value {"objects":true} (corresponding to the member 172 key "nested"), the following JSON strings evaluate to the 173 accompanying values: 175 "0/objects" true 176 "1/nested/objects" true 177 "2/foo/0" "bar" 178 "0#" "nested" 179 "1#" "highly" 181 6. Non-use in URI Fragment Identifiers 183 Unlike a JSON Pointer, a Relative JSON Pointer can not be used in a 184 URI fragment identifier. Such fragments specify exact positions 185 within a document, and therefore Relative JSON Pointers are not 186 suitable. 188 7. Error Handling 190 In the event of an error condition, evaluation of the JSON Pointer 191 fails to complete. 193 Evaluation may fail due to invalid syntax, or referencing a non- 194 existent value. This specification does not define how errors are 195 handled. An application of JSON Relative Pointer SHOULD specify the 196 impact and handling of each type of error. 198 8. Relationship to JSON Pointer 200 Relative JSON Pointers are intended as a companion to JSON Pointers. 201 Applications MUST specify the use of each syntax separately. 202 Defining either JSON Pointer or Relative JSON Pointer as an 203 acceptable syntax does not imply that the other syntax is also 204 acceptable. 206 9. Acknowledgements 208 The language and structure of this specification are based heavily on 209 [RFC6901], sometimes quoting it outright. 211 This draft remains primarily as written and published by Geraint 212 Luff, with only minor subsequent alterations under new editorship. 214 10. Security Considerations 216 Evaluation of a given Relative JSON Pointer is not guaranteed to 217 reference an actual JSON value. Applications using Relative JSON 218 Pointer should anticipate this situation by defining how a pointer 219 that does not resolve ought to be handled. 221 As part of processing, a composite data structure may be assembled 222 from multiple JSON documents (in part or in full). In such cases, 223 applications SHOULD ensure that a Relative JSON Pointer does not 224 evaluate to a value outside the document for which is was written. 226 Note that JSON pointers can contain the NUL (Unicode U+0000) 227 character. Care is needed not to misinterpret this character in 228 programming languages that use NUL to mark the end of a string. 230 11. References 232 11.1. Normative References 234 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 235 Requirement Levels", BCP 14, RFC 2119, 236 DOI 10.17487/RFC2119, March 1997, 237 . 239 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 240 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 241 DOI 10.17487/RFC6901, April 2013, 242 . 244 11.2. Informative References 246 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 247 Interchange Format", STD 90, RFC 8259, 248 DOI 10.17487/RFC8259, December 2017, 249 . 251 Appendix A. ChangeLog 253 [[CREF1: This section to be removed before leaving Internet-Draft 254 status.]] 256 draft-handrews-relative-json-pointer-02 258 * Update to the latest JSON RFC 260 draft-handrews-relative-json-pointer-01 262 * The initial number is "non-negative", not "positive" 264 draft-handrews-relative-json-pointer-00 266 * Revived draft with identical wording and structure. 268 * Clarified how to use alongside JSON Pointer. 270 draft-luff-relative-json-pointer-00 272 * Initial draft. 274 Authors' Addresses 276 Geraint Luff 277 Cambridge 278 UK 280 EMail: luffgd@gmail.com 282 Henry Andrews (editor) 284 EMail: andrews_henry@yahoo.com