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

    <front>
        <title abbrev="JSON Pointer">JSON Pointer </title>
        <author fullname="Paul C. Bryan" initials="P." surname="Bryan" role="editor">
            <organization>ForgeRock</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>Rackspace</organization>
           <address>
              <email>mnot@mnot.net</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>
            document. It 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 '~' (%x7E) or '/' (%x2F)
            characters, they MUST be encoded as '~0' and '~1'
            respectively.</t>
            
            <t><figure><preamble>ABNF syntax:</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 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 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 (after
                unescaping any backslash escape sequences that can occur in a
                JSON string) 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.</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, 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 (see <xref
            target="Errors"/>).</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>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>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>TBD</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>
        
    </back>

</rfc>