idnits 2.17.1 draft-ietf-appsawg-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 : ---------------------------------------------------------------------------- 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 (July 4, 2012) is 4314 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) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 2 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: January 5, 2013 SitePen (USA) 6 M. Nottingham, Ed. 7 Rackspace 8 July 4, 2012 10 JSON Pointer 11 draft-ietf-appsawg-json-pointer-02 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 January 5, 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 . . . . . . . . . . . . . . . . . . . . . . . . 5 59 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 60 9. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 61 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 6 62 11. Normative References . . . . . . . . . . . . . . . . . . . . . 6 63 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 7 65 1. Introduction 67 This specification defines JSON Pointer, a string syntax for 68 identifying a specific value within a JavaScript Object Notation 69 (JSON) [RFC4627] document. It is intended to be easily expressed in 70 JSON string values and Uniform Resource Identifier (URI) [RFC3986] 71 fragment identifiers. 73 2. Conventions 75 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 76 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 77 document are to be interpreted as described in [RFC2119]. 79 This specification expresses normative syntax rules using Augmented 80 Backus-Naur Form [RFC5234] (ABNF) notation. 82 3. Syntax 84 A JSON Pointer is a [Unicode] string containing a sequence of zero or 85 more reference tokens, each prefixed by a '/' (%x2F) character. 87 If a reference token contains '~' (%x7E) or '/' (%x2F) characters, 88 they MUST be encoded as '~0' and '~1' respectively. 90 ABNF syntax: 92 json-pointer = *( "/" reference-token ) 93 reference-token = *( unescaped / escaped ) 94 unescaped = %x00-2E / %x30-7D / %x7F-10FFFF 95 escaped = "~" ( "0" / "1" ) 97 It is an error condition if a JSON Pointer value does not conform to 98 this syntax (see Section 7). 100 4. Evaluation 102 Evaluation of a JSON Pointer begins with a reference to the root 103 value of a JSON text document and completes with a reference to some 104 value within the document. Each reference token in the JSON Pointer 105 is sequentially evaluated. 107 Evaluation of each reference token begins by decoding any escaped 108 character sequence; this is performed by first transforming any 109 occurrence of the sequence '~1' to '/', then transforming any 110 occurrence of the sequence '~0' to '~'. 112 The reference token then modifies which value is referenced according 113 to the following scheme: 115 If the currently referenced value is a JSON object, the new 116 referenced value is the object member with the name (after 117 unescaping any backslash escape sequences that can occur in a JSON 118 string) identified by the reference token. The member name is 119 equal to the token if it has the same number of Unicode characters 120 as token and their code points are position-wise equal. If a 121 referenced member name is not unique in an object, the member that 122 is referenced is undefined. 124 If the currently referenced value is a JSON array, the reference 125 token MUST contain characters that represent an unsigned base-10 126 integer value (possibly with leading zeros), and the new 127 referenced value is the array element with the zero-based index 128 identified by the token. 130 If a reference token is being evaluated against a JSON document, the 131 implementation MAY evaluate each token against a concrete value, and 132 terminate evaluation with an error condition if a evaluation fails to 133 resolve a concrete value (see Section 7). 135 5. JSON String Representation 137 A JSON Pointer can be represented in a JSON string value. Per 138 [RFC4627], section 2.5, all instances of quotation mark '"' (%x22), 139 reverse solidus '\' (%x5C) and control (%x00-1F) characters MUST be 140 escaped. 142 For example, given the JSON document 144 { 145 "foo": ["bar", "baz"], 146 "": 0 147 "a/b": 1, 148 "c%d": 2, 149 "e^f": 3, 150 "g|h": 4, 151 "i\\j": 5, 152 "k\"l": 6, 153 " ": 7, 154 "m~n": 8 155 } 156 Then the following JSON strings evaluate to the accompanying values: 158 "" // the whole document 159 "/foo" ["bar", "baz"] 160 "/foo/0" "bar" 161 "/" 0 162 "/a~1b" 1 163 "/c%d" 2 164 "/e^f" 3 165 "/g|h" 4 166 "/i\\j" 5 167 "/k\"l" 6 168 " " 7 169 "m~0n" 8 171 6. URI Fragment Identifier Representation 173 A JSON Pointer can be represented in a URI fragment identifier. by 174 encoding it into octets, using UTF-8 [RFC3629], percent-encoding 175 those characters not allowed by the fragment rule in [RFC3986]. 177 Given the same example document as above, the following URI fragment 178 identifiers evaluate to the accompanying values: 180 # // the whole document 181 #/foo ["bar", "baz"] 182 #/foo/0 "bar" 183 #/ 0 184 #/a~1b 1 185 #/c%25d 2 186 #/e%5Ef 3 187 #/g%7Ch 4 188 #/i%5Cj 5 189 #/k%22l 6 190 #/%20 7 191 #/m~0n 8 193 7. Error Handling 195 In the event of an error condition, evaluation of the JSON Pointer 196 fails to complete. 198 This includes, but is not limited to: 200 o Invalid pointer syntax 202 o A pointer that references a non-existent value 204 This specification does not define how errors are handled; an 205 application of JSON Pointer SHOULD specify the impact and handling of 206 each type of error. 208 For example, some applications might stop pointer processing upon an 209 error; others may attempt to recover from missing values by inserting 210 default ones. 212 8. IANA Considerations 214 TBD 216 9. Security Considerations 218 A given JSON Pointer is not guaranteed to reference an actual JSON 219 value. Implementations should be aware of this and take appropriate 220 precautions. 222 Note that JSON pointers can contain the NUL (Unicode U+0000) 223 character, which may not be representable in all programming 224 languages. 226 10. Acknowledgements 228 The following individuals contributed ideas, feedback and wording to 229 this specification: 231 Mike Acar, Carsten Bormann, Tim Bray, Jacob Davies, Martin J. 232 Duerst, Bjoern Hoehrmann, James H. Manger, Drew Perttula, Julian 233 Reschke. 235 11. Normative References 237 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 238 Requirement Levels", BCP 14, RFC 2119, March 1997. 240 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 241 10646", STD 63, RFC 3629, November 2003. 243 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 244 Resource Identifier (URI): Generic Syntax", STD 66, 245 RFC 3986, January 2005. 247 [RFC4627] Crockford, D., "The application/json Media Type for 248 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 250 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 251 Specifications: ABNF", STD 68, RFC 5234, January 2008. 253 [Unicode] The Unicode Consortium, "The Unicode Standard, Version 254 6.0", October 2011, 255 . 257 Authors' Addresses 259 Paul C. Bryan (editor) 260 ForgeRock 262 Phone: +1 604 783 1481 263 Email: pbryan@anode.ca 265 Kris Zyp 266 SitePen (USA) 268 Phone: +1 650 968 8787 269 Email: kris@sitepen.com 271 Mark Nottingham (editor) 272 Rackspace 274 Email: mnot@mnot.net