idnits 2.17.1 draft-handrews-relative-json-pointer-01.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 (January 19, 2018) is 2282 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 2 comments (--). 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: July 23, 2018 Cloudflare, Inc. 6 January 19, 2018 8 Relative JSON Pointers 9 draft-handrews-relative-json-pointer-01 11 Abstract 13 JSON Pointer is a syntax for specifying locations in a JSON document, 14 starting from the document root. This document defines an extension 15 to the JSON Pointer syntax, allowing relative locations from within 16 the document. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on July 23, 2018. 35 Copyright Notice 37 Copyright (c) 2018 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 2 54 3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 55 4. Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 5. JSON String Representation . . . . . . . . . . . . . . . . . 4 57 5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 4 58 6. Non-use in URI Fragment Identifiers . . . . . . . . . . . . . 5 59 7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 5 60 8. Relationship to JSON Pointer . . . . . . . . . . . . . . . . 5 61 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 5 62 10. Security Considerations . . . . . . . . . . . . . . . . . . . 5 63 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 64 11.1. Normative References . . . . . . . . . . . . . . . . . . 6 65 11.2. Informative References . . . . . . . . . . . . . . . . . 6 66 Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 7 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7 69 1. Introduction 71 JSON Pointer (RFC 6901 [RFC6901]) is a syntax for specifying 72 locations in a JSON document, starting from the document root. This 73 document defines a related syntax allowing identification of relative 74 locations from within the document. 76 2. Conventions and Terminology 78 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 79 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 80 document are to be interpreted as described in RFC 2119 [RFC2119]. 82 3. Syntax 84 A Relative JSON Pointer is a Unicode string (see RFC 4627, Section 3 85 [RFC4627]), comprising a non-negative integer, followed by either a 86 '#' (%x23) character or a JSON Pointer (RFC 6901 [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 [RFC4627] Crockford, D., "The application/json Media Type for 247 JavaScript Object Notation (JSON)", RFC 4627, 248 DOI 10.17487/RFC4627, July 2006, 249 . 251 Appendix A. ChangeLog 253 [[CREF1: This section to be removed before leaving Internet-Draft 254 status.]] 256 draft-handrews-relative-json-pointer-01 258 * The initial number is "non-negative", not "positive" 260 draft-handrews-relative-json-pointer-00 262 * Revived draft with identical wording and structure. 264 * Clarified how to use alongside JSON Pointer. 266 draft-luff-relative-json-pointer-00 268 * Initial draft. 270 Authors' Addresses 272 Geraint Luff 273 Cambridge 274 UK 276 EMail: luffgd@gmail.com 278 Henry Andrews (editor) 279 Cloudflare, Inc. 280 San Francisco, CA 281 USA 283 EMail: henry@cloudflare.com