draft-ietf-appsawg-json-pointer-06.txt   draft-ietf-appsawg-json-pointer-07.txt 
Applications Area Working Group P. Bryan, Ed. Applications Area Working Group P. Bryan, Ed.
Internet-Draft Salesforce.com Internet-Draft Salesforce.com
Intended status: Informational K. Zyp Intended status: Informational K. Zyp
Expires: June 8, 2013 SitePen (USA) Expires: June 14, 2013 SitePen (USA)
M. Nottingham, Ed. M. Nottingham, Ed.
Akamai Akamai
December 5, 2012 December 11, 2012
JSON Pointer JSON Pointer
draft-ietf-appsawg-json-pointer-06 draft-ietf-appsawg-json-pointer-07
Abstract Abstract
JSON Pointer defines a string syntax for identifying a specific value JSON Pointer defines a string syntax for identifying a specific value
within a JSON document. within a JSON document.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
skipping to change at page 1, line 34 skipping to change at page 1, line 34
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on June 8, 2013. This Internet-Draft will expire on June 14, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 15 skipping to change at page 2, line 15
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . 3
5. JSON String Representation . . . . . . . . . . . . . . . . . . 4 5. JSON String Representation . . . . . . . . . . . . . . . . . . 4
6. URI Fragment Identifier Representation . . . . . . . . . . . . 5 6. URI Fragment Identifier Representation . . . . . . . . . . . . 5
7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 6 7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 6
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6
9. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 9. Security Considerations . . . . . . . . . . . . . . . . . . . . 7
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7
11.1. Normative References . . . . . . . . . . . . . . . . . . . 7 11.1. Normative References . . . . . . . . . . . . . . . . . . . 7
11.2. Informative References . . . . . . . . . . . . . . . . . . 7 11.2. Informative References . . . . . . . . . . . . . . . . . . 7
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 7 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8
1. Introduction 1. Introduction
This specification defines JSON Pointer, a string syntax for This specification defines JSON Pointer, a string syntax for
identifying a specific value within a JavaScript Object Notation identifying a specific value within a JavaScript Object Notation
(JSON) [RFC4627] document. It is intended to be easily expressed in (JSON) [RFC4627] document. It is intended to be easily expressed in
JSON string values as well as Uniform Resource Identifier (URI) JSON string values as well as Uniform Resource Identifier (URI)
[RFC3986] fragment identifiers. [RFC3986] fragment identifiers.
2. Conventions 2. Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
This specification expresses normative syntax rules using Augmented This specification expresses normative syntax rules using Augmented
Backus-Naur Form (ABNF) [RFC5234] notation. Backus-Naur Form (ABNF) [RFC5234] notation.
3. Syntax 3. Syntax
A JSON Pointer is a [Unicode] string containing a sequence of zero or A JSON Pointer is a Unicode string (see [RFC4627], Section 3)
more reference tokens, each prefixed by a '/' (%x2F) character. containing a sequence of zero or more reference tokens, each prefixed
by a '/' (%x2F) character.
Since the characters '~' (%x7E) and '/' (%x2F) have a special meaning Because the characters '~' (%x7E) and '/' (%x2F) have special
in JSON Pointer, they need to be encoded as '~0' and '~1' meanings in JSON Pointer, '~' needs to be encoded as '~0' and '/'
respectively, when appearing in a reference token. needs to be encoded as '~1' when these characters appear in a
reference token.
Its ABNF syntax is: The ABNF syntax of a JSON Pointer is:
json-pointer = *( "/" reference-token ) json-pointer = *( "/" reference-token )
reference-token = *( unescaped / escaped ) reference-token = *( unescaped / escaped )
unescaped = %x00-2E / %x30-7D / %x7F-10FFFF unescaped = %x00-2E / %x30-7D / %x7F-10FFFF
; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
escaped = "~" ( "0" / "1" ) escaped = "~" ( "0" / "1" )
; representing '~' and '/', respectively
It is an error condition if a JSON Pointer value does not conform to It is an error condition if a JSON Pointer value does not conform to
this syntax (see Section 7). this syntax (see Section 7).
4. Evaluation 4. Evaluation
Evaluation of a JSON Pointer begins with a reference to the root Evaluation of a JSON Pointer begins with a reference to the root
value of a JSON document and completes with a reference to some value value of a JSON document and completes with a reference to some value
within the document. Each reference token in the JSON Pointer is within the document. Each reference token in the JSON Pointer is
sequentially evaluated. sequentially evaluated. By performing the substitutions in this
order, an implementation avoids the error of turning '~01' first into
'~1' and then into '/', which would be incorrect (the string '~01'
correctly becomes '~1' after transformation).
Evaluation of each reference token begins by decoding any escaped Evaluation of each reference token begins by decoding any escaped
character sequence; this is performed by first transforming any character sequence; this is performed by first transforming any
occurrence of the sequence '~1' to '/', then transforming any occurrence of the sequence '~1' to '/', then transforming any
occurrence of the sequence '~0' to '~'. occurrence of the sequence '~0' to '~'.
The reference token then modifies which value is referenced according The reference token then modifies which value is referenced according
to the following scheme: to the following scheme:
o If the currently referenced value is a JSON object, the new o If the currently referenced value is a JSON object, the new
referenced value is the object member with the name identified by referenced value is the object member with the name identified by
the reference token. The member name is equal to the token if it the reference token. The member name is equal to the token if it
has the same number of Unicode characters as token and their code has the same number of Unicode characters as token and their code
points are position-wise equal. If a referenced member name is points are position-wise equal. No Unicode character
not unique in an object, the member that is referenced is normalization is performed. If a referenced member name is not
undefined, and evaluation fails (see below). unique in an object, the member that is referenced is undefined,
and evaluation fails (see below).
o If the currently referenced value is a JSON array, the reference o If the currently referenced value is a JSON array, the reference
token MUST contain either: token MUST contain either:
* characters that represent an unsigned base-10 integer value * characters that represent an unsigned base-10 integer value
(possibly with leading zeros), making the new referenced value (possibly with leading zeros), making the new referenced value
the array element with the zero-based index identified by the the array element with the zero-based index identified by the
token, or token, or
* exactly the single character "-", making the new referenced * exactly the single character "-", making the new referenced
skipping to change at page 6, line 44 skipping to change at page 7, line 8
error; others may attempt to recover from missing values by inserting error; others may attempt to recover from missing values by inserting
default ones. default ones.
8. IANA Considerations 8. IANA Considerations
This document has no impact upon IANA. This document has no impact upon IANA.
9. Security Considerations 9. Security Considerations
A given JSON Pointer is not guaranteed to reference an actual JSON A given JSON Pointer is not guaranteed to reference an actual JSON
value. Implementations should be aware of this and take appropriate value. Therefore, applications using JSON Pointer should anticipate
precautions. this by defining how a pointer that does not resolve ought to be
handled.
Note that JSON pointers can contain the NUL (Unicode U+0000) Note that JSON pointers can contain the NUL (Unicode U+0000)
character. Care is needed not to misinterpret this character in character. Care is needed not to misinterpret this character in
programming languages that use NUL to mark the end of a string. programming languages that use NUL to mark the end of a string.
10. Acknowledgements 10. Acknowledgements
The following individuals contributed ideas, feedback and wording to The following individuals contributed ideas, feedback and wording to
this specification: this specification:
skipping to change at page 7, line 34 skipping to change at page 7, line 45
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC4627] Crockford, D., "The application/json Media Type for [RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008. Specifications: ABNF", STD 68, RFC 5234, January 2008.
[Unicode] The Unicode Consortium, "The Unicode Standard, Version
6.0", October 2011,
<http://www.unicode.org/versions/Unicode6.0.0/>.
11.2. Informative References 11.2. Informative References
[RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and
Registration Procedures", BCP 13, RFC 4288, December 2005. Registration Procedures", BCP 13, RFC 4288, December 2005.
Authors' Addresses Authors' Addresses
Paul C. Bryan (editor) Paul C. Bryan (editor)
Salesforce.com Salesforce.com
 End of changes. 15 change blocks. 
22 lines changed or deleted 27 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/