One document matched: draft-ietf-appsawg-json-pointer-04.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="info" docName="draft-ietf-appsawg-json-pointer-04" ipr="trust200902">
<front>
<title abbrev="JSON Pointer">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></organization>
<address>
<email>mnot@mnot.net</email>
</address>
</author>
<date year="2012"/>
<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 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 <xref target="Unicode"/> string containing
a sequence of zero or more reference tokens, each prefixed by a
'/' (%x2F) character.</t>
<t>Since the characters '~' (%x7E) and '/' (%x2F) have a special
meaning in JSON Pointer, they need to be encoded as '~0' and '~1'
respectively, when appearing in a reference token.</t>
<t><figure><preamble>Its ABNF syntax is:</preamble><artwork><![CDATA[
json-pointer = *( "/" reference-token )
reference-token = *( unescaped / escaped )
unescaped = %x00-2E / %x30-7D / %x7F-10FFFF
escaped = "~" ( "0" / "1" )
]]> </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>
</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 '~'.</t>
<t>The reference token then modifies which value is referenced
according to the following scheme:</t>
<t><list>
<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 token and
their code points are position-wise equal. 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 characters that represent an
unsigned base-10 integer value (possibly with leading zeros),
and the new referenced value is the array element with the
zero-based index identified by the token.</t>
</list></t>
<t>If a reference token is being evaluated against a JSON
document, implementations will evaluate each token against the
document's contents, and terminate evaluation with an error
condition if it fails to resolve a concrete value for any of the
JSON pointer's reference tokens. See <xref target="Errors"/> for
details.</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 nominate 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. Implementations should be aware of this and take
appropriate precautions.</t>
<t>Note that JSON pointers can contain the NUL (Unicode U+0000)
character, which may not be representable in all programming
languages.</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;
<reference anchor="Unicode" target="http://www.unicode.org/versions/Unicode6.0.0/">
<front>
<title>The Unicode Standard, Version 6.0</title>
<author>
<organization>The Unicode Consortium</organization>
</author>
<date year="2011" month="October"/>
</front>
</reference>
</references>
<references title="Informative References">
&RFC4288;
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 01:18:31 |