One document matched: draft-ietf-appsawg-json-pointer-00.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 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-00" ipr="trust200902">

    <front>
        <title abbrev="JSON Pointer">JSON Pointer </title>
        <author fullname="Paul C. Bryan" initials="P." surname="Bryan" role="editor">
            <organization>ForgeRock US, Inc.</organization>
            <address>
                <postal>
                    <street>201 NE Park Plaza Drive Suite 196</street>
                    <city>Vancouver</city>
                    <region>WA</region>
                    <code>98684</code>
                    <country>USA</country>
                </postal>
                <phone>+1 604 783 1481</phone>
                <email>paul.bryan@forgerock.com</email>
            </address>
        </author>
        <author fullname="Kris Zyp" initials="K." surname="Zyp">
            <organization>SitePen (USA)</organization>
            <address>
                <postal>
                    <street>530 Lytton Avenue</street>
                    <city>Palo Alto</city>
                    <region>CA</region>
                    <code>94301</code>
                    <country>USA</country>
                </postal>
                <phone>+1 650 968 8787</phone>
                <email>kris@sitepen.com</email>
            </address>
            
        </author>
        <date year="2012" />
        <area>General</area>
        <workgroup>Applications Area Working Group</workgroup>
        <keyword>json</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> text document.
             This syntax is intended to be easily expressed in JSON string values and
             <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</xref> (ABNF) 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>If a reference token contains '/' (%x2F) or '\' (%x5C) characters, such
             characters MUST each be prefixed (escaped) with a '\' (%x5C) character.</t>
            <t><figure><preamble>ABNF syntax:</preamble><artwork><![CDATA[
json-pointer = *( "/" reference-token )
reference-token = *( unescaped / escaped )
unescaped = %x00-2E / %x30-5B / %x5D-10FFFF
escaped = "\" ( "/" / "\" )
]]>         </artwork></figure></t>
            <t>It is an error condition if a JSON Pointer value does not conform to this
             syntax.</t>
        </section>
        <section title="Evaluation">
            <t>Evaluation of a JSON Pointer begins with a reference to the root value of a
             JSON text 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 unescaping any escaped character
             sequence; this is performed by simply the '\' (escape) prefix. The reference
             token then modifies which value is referenced according to the following
             scheme:<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. If a referenced member name is not unique, which member is
                 referenced is undefined.</t>
                <t>If the currently referenced value is a JSON array, the reference token MUST
                 contain an unsigned base-10 integer value, 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 concrete JSON document,
             the implementation MAY evaluate each token against a concrete value, and
             terminate evaluation with an error condition if a evaluation fails to resolve a
             concrete value.</t>
        </section>
 
        <section title="JSON String Representation">
            <t>A JSON Pointer MAY 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>
        </section>

        <section title="URI Fragment Identifier Representation">
            <t>A JSON Pointer MAY be represented in a URI fragment identifier. The JSON
            pointer MUST be <xref target="RFC3629">UTF-8</xref> encoded as octets; octets in
            the URI "unreserved" set SHOULD be percent-encoded, per
            <xref target="RFC3986" />, section 2.5.</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>
        </section>

        <section anchor="IANA" title="IANA Considerations">
            <t>This document has no IANA actions.</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>
        </section>

        <section title="Acknowledgements">
            <t>The following individuals contributed ideas, feedback and wording, which
             contributed to the content of this specification:<list>
                <t>Carsten Bormann, Jacob Davies, Martin J. Dürst, Björn Höhrmann,
                 Mark Nottingham, 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>

        <section title="Examples">
            <t>
                <figure>
                    <preamble>The following examples illustrate the use of JSON Pointers in
                    URI fragments for a JSON text document located at
                    http://example.com/example.json, with the following value:</preamble>
                    <artwork><![CDATA[
{
    "foo": {
        "bar": [ "element0", "element1" ],
        "inner object": {
            "baz": "qux"
    }
}
]]>                 </artwork>
                </figure>
            </t>
            <t><list style="hanging">
                <t hangText="http://example.com/example.json#"><vspace />Resolves to the object
                 value at the root of the JSON text document.</t>
                <t hangText="http://example.com/example.json#/foo"><vspace />Resolves to the
                 object value of the "foo" member in the root object.</t>
                <t hangText="http://example.com/example.json#/foo/inner%20object"><vspace />Resolves
                 to the object value of the "inner object" member in the "foo" object value in the root object.</t>
                <t hangText="http://example.com/example.json#/foo/inner%20object/baz"><vspace />Resolves
                 to the string value "qux", which is the value of the "baz" member in the
                 "inner object" member in the "foo" member in the root
                 object.</t>
                <t hangText="http://example.com/example.json#/foo/bar/0"><vspace />Resolves to
                 the string value "element0", which is the first value in the "bar" array in
                 the "foo" member in the root object.</t>
            </list></t>
        </section>
        
    </back>

</rfc>