One document matched: draft-ietf-appsawg-json-pointer-01.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-01" 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>
        <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 '^' (%x5E) characters, such
             characters MUST each be prefixed (escaped) with a '^' (%x5E) 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 removing 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. The member name is equal to the token if it has the same number of
                 Unicode characters as token and their codepoints are positionwise 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, 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.</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
            not 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>Mike Acar, Carsten Bormann, Tim Bray, Jacob Davies, Martin J. Dürst,
                 Björn Höhrmann, James H. Manger, 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>