One document matched: draft-ietf-appsawg-json-pointer-09.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC3629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3629.xml">
<!ENTITY RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY RFC2616 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml">
<!ENTITY RFC4288 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4288.xml">
<!ENTITY RFC4627 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml">
<!ENTITY RFC5234 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc strict="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<rfc category="std" docName="draft-ietf-appsawg-json-pointer-09" ipr="trust200902">
<front>
<title abbrev="JSON Pointer">JavaScript Object Notation (JSON) Pointer </title>
<author fullname="Paul C. Bryan" initials="P." surname="Bryan" role="editor">
<organization>Salesforce.com</organization>
<address>
<phone>+1 604 783 1481</phone>
<email>pbryan@anode.ca</email>
</address>
</author>
<author fullname="Kris Zyp" initials="K." surname="Zyp">
<organization>SitePen (USA)</organization>
<address>
<phone>+1 650 968 8787</phone>
<email>kris@sitepen.com</email>
</address>
</author>
<author fullname="Mark Nottingham" initials="M." surname="Nottingham"
role="editor">
<organization>Akamai</organization>
<address>
<email>mnot@mnot.net</email>
</address>
</author>
<date year="2013"/>
<area>General</area>
<workgroup>Applications Area Working Group</workgroup>
<keyword>json</keyword>
<keyword>pointer</keyword>
<abstract>
<t>JSON Pointer defines a string syntax for identifying a specific
value within a JavaScript Object Notation (JSON) document.</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>This specification defines JSON Pointer, a string syntax for
identifying a specific value within a <xref
target="RFC4627">JavaScript Object Notation (JSON)</xref>
document. It is intended to be easily expressed in JSON string
values as well as <xref target="RFC3986">Uniform Resource Identifier
(URI)</xref> fragment identifiers.</t>
</section>
<section title="Conventions">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
in this document are to be interpreted as described in <xref
target="RFC2119"/>.</t>
<t>This specification expresses normative syntax rules using <xref
target="RFC5234">Augmented Backus-Naur Form (ABNF)</xref>
notation.</t>
</section>
<section title="Syntax">
<t>A JSON Pointer is a Unicode string (see <xref
target="RFC4627"/>, Section 3) containing a sequence of zero or
more reference tokens, each prefixed by a '/' (%x2F)
character.</t>
<t>Because the characters '~' (%x7E) and '/' (%x2F) have special
meanings in JSON Pointer, '~' needs to be encoded as '~0' and '/'
needs to be encoded as '~1' when these characters appear in a
reference token.</t>
<t><figure><preamble>The ABNF syntax of a JSON Pointer is:</preamble><artwork><![CDATA[
json-pointer = *( "/" reference-token )
reference-token = *( unescaped / escaped )
unescaped = %x00-2E / %x30-7D / %x7F-10FFFF
; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
escaped = "~" ( "0" / "1" )
; representing '~' and '/', respectively
]]> </artwork></figure></t>
<t>It is an error condition if a JSON Pointer value does not
conform to this syntax (see <xref target="Errors"/>).</t>
<t>Note that JSON Pointers are specified in characters, not
as bytes.</t>
</section>
<section title="Evaluation">
<t>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 within the document. Each reference token in the JSON
Pointer is sequentially evaluated.</t>
<t>Evaluation of each reference token begins by decoding any
escaped character sequence; this is performed by first
transforming any occurrence of the sequence '~1' to '/', then
transforming any occurrence of the sequence '~0' to '~'. 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).</t>
<t>The reference token then modifies which value is referenced
according to the following scheme:</t>
<t><list style="symbols">
<t>If the currently referenced value is a JSON object, the new
referenced value is the object member with the name identified
by the reference token. The member name is equal to the token
if it has the same number of Unicode characters as the token
and their code points are position-wise equal. No Unicode
character normalization is performed. If a referenced member
name is not unique in an object, the member that is referenced
is undefined, and evaluation fails (see below).</t>
<t>If the currently referenced value is a JSON array, the
reference token MUST contain either:
<list style="symbols">
<t>characters comprised of digits (see ABNF below; note
that leading zeros are not allowed) that represent an
unsigned base-10 integer value, making the new referenced
value the array element with the zero-based index
identified by the token, or</t>
<t>exactly the single character "-", making the new
referenced value the (non-existant) member after the last
array element.</t>
</list></t>
</list></t>
<t><figure><preamble>The ABNF syntax for array indices is:</preamble><artwork><![CDATA[
array-index = %x30 / ( %x31-39 *(%x30-39) )
; "0", or digits without a leading "0"
]]> </artwork></figure></t>
<t>Implementations will evaluate each reference token against the
document's contents, and will raise an error condition if it fails
to resolve a concrete value for any of the JSON pointer's
reference tokens. For example, if an array is referenced with a
non-numeric token, an error condition will be raised. See <xref
target="Errors"/> for details.</t>
<t>Note that the use of the "-" character to index an array will
always result in such an error condition because by definition it
refers to a non-existent array element. Applications of JSON
Pointer thus need to specify how it is to be handled, if it is to
be useful.</t>
<t>Any error condition that does not have a specific action
defined for it by the JSON Pointer application results in
termination of evaluation.</t>
</section>
<section title="JSON String Representation">
<t>A JSON Pointer can be represented in a JSON string value. Per
<xref target="RFC4627"/>, Section 2.5, all instances of quotation
mark '"' (%x22), reverse solidus '\' (%x5C) and control (%x00-1F)
characters MUST be escaped.</t>
<t>Note that before processing a JSON string as a JSON Pointer,
backslash escape sequences must be unescaped.</t>
<t>For example, given the JSON document</t>
<t><figure><artwork><![CDATA[
{
"foo": ["bar", "baz"],
"": 0,
"a/b": 1,
"c%d": 2,
"e^f": 3,
"g|h": 4,
"i\\j": 5,
"k\"l": 6,
" ": 7,
"m~n": 8
}
]]> </artwork></figure></t>
<t>Then the following JSON strings evaluate to the accompanying
values:</t>
<t><figure><artwork><![CDATA[
"" // the whole document
"/foo" ["bar", "baz"]
"/foo/0" "bar"
"/" 0
"/a~1b" 1
"/c%d" 2
"/e^f" 3
"/g|h" 4
"/i\\j" 5
"/k\"l" 6
"/ " 7
"/m~0n" 8
]]> </artwork></figure></t>
</section>
<section title="URI Fragment Identifier Representation">
<t>A JSON Pointer can be represented in a URI fragment identifier
by encoding it into octets using <xref
target="RFC3629">UTF-8</xref>, percent-encoding those characters
not allowed by the fragment rule in <xref target="RFC3986"/>.</t>
<t>Note that a given media type needs to specify JSON Pointer as
its fragment identifier syntax explicitly (usually, in its
registration <xref target="RFC4288"/>); i.e., just because a
document is JSON does not imply that JSON Pointer can be used as
its fragment identifier syntax. In particular, the fragment
identifier syntax for application/json is not JSON Pointer.</t>
<t>Given the same example document as above, the following URI
fragment identifiers evaluate to the accompanying values:</t>
<t><figure><artwork><![CDATA[
# // the whole document
#/foo ["bar", "baz"]
#/foo/0 "bar"
#/ 0
#/a~1b 1
#/c%25d 2
#/e%5Ef 3
#/g%7Ch 4
#/i%5Cj 5
#/k%22l 6
#/%20 7
#/m~0n 8
]]> </artwork></figure></t>
</section>
<section anchor="Errors" title="Error Handling">
<t>In the event of an error condition, evaluation of the JSON
Pointer fails to complete.</t>
<t>This includes, but is not limited to:</t>
<t><list style="symbols">
<t>Invalid pointer syntax</t>
<t>A pointer that references a non-existent value</t>
</list></t>
<t>This specification does not define how errors are handled;
an application of JSON Pointer SHOULD specify the impact
and handling of each type of error.</t>
<t>For example, some applications might stop pointer processing
upon an error; others may attempt to recover from missing
values by inserting default ones.</t>
</section>
<section anchor="IANA" title="IANA Considerations">
<t>This document has no impact upon IANA.</t>
</section>
<section anchor="Security" title="Security Considerations">
<t>A given JSON Pointer is not guaranteed to reference an actual
JSON value. Therefore, applications using JSON Pointer should
anticipate this by defining how a pointer that does not resolve
ought to be handled.</t>
<t>Note that JSON pointers can contain the NUL (Unicode U+0000)
character. Care is needed not to misinterpret this character in
programming languages that use NUL to mark the end of a
string.</t>
</section>
<section title="Acknowledgements">
<t>The following individuals contributed ideas, feedback and
wording to this specification:<list>
<t>Mike Acar, Carsten Bormann, Tim Bray, Jacob Davies, Martin
J. Dürst, Björn Höhrmann, James H. Manger,
Drew Perttula, Julian Reschke.</t>
</list></t>
</section>
</middle>
<back>
<references title="Normative References">
&RFC2119;
&RFC3629;
&RFC3986;
&RFC4627;
&RFC5234;
</references>
<references title="Informative References">
&RFC4288;
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 02:37:21 |