idnits 2.17.1 draft-pbryan-zyp-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 178 has weird spacing: '...rop/baz the s...' -- The document date (June 9, 2011) is 4705 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2396 (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force P. Bryan, Ed. 3 Internet-Draft ForgeRock US, Inc. 4 Intended status: Informational K. Zyp 5 Expires: December 11, 2011 SitePen (USA) 6 June 9, 2011 8 JSON Pointer 9 draft-pbryan-zyp-json-pointer-00 11 Abstract 13 JSON Pointer provides a syntax for identifying a specific node within 14 a JSON document. 16 Status of this Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on December 11, 2011. 33 Copyright Notice 35 Copyright (c) 2011 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 4. Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 5. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 4 55 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 4 56 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 4 57 8. Security Considerations . . . . . . . . . . . . . . . . . . . . 4 58 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 9.1. Normative References . . . . . . . . . . . . . . . . . . . 4 60 9.2. Informative References . . . . . . . . . . . . . . . . . . 4 61 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . . 5 62 Appendix B. Changelog . . . . . . . . . . . . . . . . . . . . . . 5 63 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . . 5 64 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 5 66 1. Introduction 68 This Internet-Draft proposes JSON Pointer, a syntax for identifying a 69 specific node within a JSON [RFC4627] document. The syntax is 70 intended to be expressed in a JSON string value or in a URL fragment 71 identifier for a resource with a JSON representation. 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 3. Syntax 81 A JSON Pointer is a sequence of zero or more property reference 82 tokens, starting with and separated by the "/" (\x2F) character. 83 Each property reference token is a sequence of unreserved characters 84 or escape sequences per [RFC2396]. 86 pointer = "/" 0*1( token *( "/" token ) ) 87 token = 1* 89 It is an error condition if a JSON Pointer does not conform to this 90 syntax. 92 4. Evaluation 94 A JSON Pointer is evaluated against a target JSON document and yields 95 a target node. Evaluation begins with the initial target node being 96 the JSON document itself. For each property reference token, a new 97 target node is selected from the current target node. 99 If the current target node is a JSON object, then the new target is 100 the value of the property with the name identified by the next 101 property reference token. If the current target node is a JSON 102 array, then the new target is the value of the item in the array with 103 the zero-based index identified by the next property reference token 104 (which MUST be a non-negative integer number value). 106 It is an error condition if a property reference token fails to 107 resolve a value for the current target node. The target node is 108 successively updated for each property reference token until the 109 entire sequence of property reference tokens is evaluated. 111 Property names SHOULD be URI encoded per [RFC2396]. In particular, 112 any "/" character in a property name MUST be encoded as "%2F" to 113 avoid being interpreted as a property reference token separator. 115 5. Error Handling 117 In the event of an error condition, evaluation of the JSON Pointer 118 fails to complete. 120 6. Acknowledgements 122 This specification originated from the [JSON Schema] specification. 124 7. IANA Considerations 126 This draft includes no request to IANA. 128 8. Security Considerations 130 This draft includes no security considerations. 132 9. References 134 9.1. Normative References 136 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 137 Requirement Levels", BCP 14, RFC 2119, March 1997. 139 [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 140 Resource Identifiers (URI): Generic Syntax", RFC 2396, 141 August 1998. 143 [RFC4627] Crockford, D., "The application/json Media Type for 144 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 146 9.2. Informative References 148 [JSON Schema] 149 Zyp, K. and G. Court, "A JSON Media Type for Describing 150 the Structure and Meaning of JSON Documents", 151 November 2010, 152 . 154 Appendix A. Examples 156 For example, for the following JSON representation: 158 { 159 "foo": { 160 "anArray": [ 161 { "prop": 44 } 162 ], 163 "another prop": { 164 "baz": "A string" 165 } 166 } 167 } 169 The following JSON Pointers would be resolved: 171 JSON Pointer resolution 172 ------------------- ---------- 173 / self, the root of the resource itself 174 /foo the object referred to by the foo property 175 /foo/another%20prop the object referred to by the "another prop" 176 property of the object referred to by the 177 "foo" property 178 /foo/another%20prop/baz the string referred to by the value of "baz" 179 property of the "another prop" property of 180 the object referred to by the "foo" property 181 /foo/anArray/0 the first object in the "anArray" array 183 Appendix B. Changelog 185 draft-00 187 Initial draft. 189 Appendix C. Open Issues 191 TBD 193 Authors' Addresses 195 Paul C. Bryan (editor) 196 ForgeRock US, Inc. 197 201 NE Park Plaza Drive Suite 196 198 Vancouver, WA 98684 199 USA 201 Phone: +1 604 783 1481 202 Email: paul.bryan@forgerock.com 204 Kris Zyp 205 SitePen (USA) 206 530 Lytton Avenue 207 Palo Alto, CA 94301 208 USA 210 Phone: +1 650 968 8787 211 Email: kris@sitepen.com