idnits 2.17.1 draft-ietf-appsawg-json-pointer-03.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 11, 2012) is 4248 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: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) -- Obsolete informational reference (is this intentional?): RFC 4288 (Obsoleted by RFC 6838) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Applications Area Working Group P. Bryan, Ed. 3 Internet-Draft ForgeRock 4 Intended status: Informational K. Zyp 5 Expires: February 12, 2013 SitePen (USA) 6 M. Nottingham, Ed. 7 Rackspace 8 August 11, 2012 10 JSON Pointer 11 draft-ietf-appsawg-json-pointer-03 13 Abstract 15 JSON Pointer defines a string syntax for identifying a specific value 16 within a JSON 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 http://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 February 12, 2013. 35 Copyright Notice 37 Copyright (c) 2012 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 (http://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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 4. Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 5. JSON String Representation . . . . . . . . . . . . . . . . . . 4 57 6. URI Fragment Identifier Representation . . . . . . . . . . . . 5 58 7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 6 59 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 60 9. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 61 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 6 62 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 63 11.1. Normative References . . . . . . . . . . . . . . . . . . . 7 64 11.2. Informative References . . . . . . . . . . . . . . . . . . 7 65 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 7 67 1. Introduction 69 This specification defines JSON Pointer, a string syntax for 70 identifying a specific value within a JavaScript Object Notation 71 (JSON) [RFC4627] document. It is intended to be easily expressed in 72 JSON string values as well as Uniform Resource Identifier (URI) 73 [RFC3986] fragment identifiers. 75 2. Conventions 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 [RFC2119]. 81 This specification expresses normative syntax rules using Augmented 82 Backus-Naur Form [RFC5234] (ABNF) notation. 84 3. Syntax 86 A JSON Pointer is a [Unicode] string containing a sequence of zero or 87 more reference tokens, each prefixed by a '/' (%x2F) character. 89 If a reference token contains '~' (%x7E) or '/' (%x2F) characters, 90 they MUST be encoded as '~0' and '~1' respectively. 92 Its ABNF syntax is: 94 json-pointer = *( "/" reference-token ) 95 reference-token = *( unescaped / escaped ) 96 unescaped = %x00-2E / %x30-7D / %x7F-10FFFF 97 escaped = "~" ( "0" / "1" ) 99 It is an error condition if a JSON Pointer value does not conform to 100 this syntax (see Section 7). 102 4. Evaluation 104 Evaluation of a JSON Pointer begins with a reference to the root 105 value of a JSON document and completes with a reference to some value 106 within the document. Each reference token in the JSON Pointer is 107 sequentially evaluated. 109 Evaluation of each reference token begins by decoding any escaped 110 character sequence; this is performed by first transforming any 111 occurrence of the sequence '~1' to '/', then transforming any 112 occurrence of the sequence '~0' to '~'. 114 The reference token then modifies which value is referenced according 115 to the following scheme: 117 If the currently referenced value is a JSON object, the new 118 referenced value is the object member with the name (after 119 unescaping any backslash escape sequences that can occur in a JSON 120 string) identified by the reference token. The member name is 121 equal to the token if it has the same number of Unicode characters 122 as token and their code points are position-wise equal. If a 123 referenced member name is not unique in an object, the member that 124 is referenced is undefined, and evaluation fails (see below). 126 If the currently referenced value is a JSON array, the reference 127 token MUST contain characters that represent an unsigned base-10 128 integer value (possibly with leading zeros), and the new 129 referenced value is the array element with the zero-based index 130 identified by the token. 132 If a reference token is being evaluated against a JSON document, 133 implementations will evaluate each token against the document's 134 contents, and terminate evaluation with an error condition if it 135 fails to resolve a concrete value for any of the JSON pointer's 136 reference tokens. See Section 7 for details. 138 5. JSON String Representation 140 A JSON Pointer can be represented in a JSON string value. Per 141 [RFC4627], section 2.5, all instances of quotation mark '"' (%x22), 142 reverse solidus '\' (%x5C) and control (%x00-1F) characters MUST be 143 escaped. 145 For example, given the JSON document 147 { 148 "foo": ["bar", "baz"], 149 "": 0, 150 "a/b": 1, 151 "c%d": 2, 152 "e^f": 3, 153 "g|h": 4, 154 "i\\j": 5, 155 "k\"l": 6, 156 " ": 7, 157 "m~n": 8 159 } 161 Then the following JSON strings evaluate to the accompanying values: 163 "" // the whole document 164 "/foo" ["bar", "baz"] 165 "/foo/0" "bar" 166 "/" 0 167 "/a~1b" 1 168 "/c%d" 2 169 "/e^f" 3 170 "/g|h" 4 171 "/i\\j" 5 172 "/k\"l" 6 173 "/ " 7 174 "/m~0n" 8 176 6. URI Fragment Identifier Representation 178 A JSON Pointer can be represented in a URI fragment identifier. by 179 encoding it into octets, using UTF-8 [RFC3629], percent-encoding 180 those characters not allowed by the fragment rule in [RFC3986]. 182 Note that a given media type needs to nominate JSON Pointer as its 183 fragment identifier syntax explicitly (usually, in its registration 184 [RFC4288]); i.e., just because a document is JSON does not imply that 185 JSON Pointer can be used as its fragment identifier syntax. 187 Given the same example document as above, the following URI fragment 188 identifiers evaluate to the accompanying values: 190 # // the whole document 191 #/foo ["bar", "baz"] 192 #/foo/0 "bar" 193 #/ 0 194 #/a~1b 1 195 #/c%25d 2 196 #/e%5Ef 3 197 #/g%7Ch 4 198 #/i%5Cj 5 199 #/k%22l 6 200 #/%20 7 201 #/m~0n 8 203 7. Error Handling 205 In the event of an error condition, evaluation of the JSON Pointer 206 fails to complete. 208 This includes, but is not limited to: 210 o Invalid pointer syntax 212 o A pointer that references a non-existent value 214 This specification does not define how errors are handled; an 215 application of JSON Pointer SHOULD specify the impact and handling of 216 each type of error. 218 For example, some applications might stop pointer processing upon an 219 error; others may attempt to recover from missing values by inserting 220 default ones. 222 8. IANA Considerations 224 This document has no impact upon IANA. 226 9. Security Considerations 228 A given JSON Pointer is not guaranteed to reference an actual JSON 229 value. Implementations should be aware of this and take appropriate 230 precautions. 232 Note that JSON pointers can contain the NUL (Unicode U+0000) 233 character, which may not be representable in all programming 234 languages. 236 10. Acknowledgements 238 The following individuals contributed ideas, feedback and wording to 239 this specification: 241 Mike Acar, Carsten Bormann, Tim Bray, Jacob Davies, Martin J. 242 Duerst, Bjoern Hoehrmann, James H. Manger, Drew Perttula, Julian 243 Reschke. 245 11. References 246 11.1. Normative References 248 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 249 Requirement Levels", BCP 14, RFC 2119, March 1997. 251 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 252 10646", STD 63, RFC 3629, November 2003. 254 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 255 Resource Identifier (URI): Generic Syntax", STD 66, 256 RFC 3986, January 2005. 258 [RFC4627] Crockford, D., "The application/json Media Type for 259 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 261 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 262 Specifications: ABNF", STD 68, RFC 5234, January 2008. 264 [Unicode] The Unicode Consortium, "The Unicode Standard, Version 265 6.0", October 2011, 266 . 268 11.2. Informative References 270 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 271 Registration Procedures", BCP 13, RFC 4288, December 2005. 273 Authors' Addresses 275 Paul C. Bryan (editor) 276 ForgeRock 278 Phone: +1 604 783 1481 279 Email: pbryan@anode.ca 281 Kris Zyp 282 SitePen (USA) 284 Phone: +1 650 968 8787 285 Email: kris@sitepen.com 286 Mark Nottingham (editor) 287 Rackspace 289 Email: mnot@mnot.net