One document matched: draft-pbryan-zyp-json-pointer-02.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.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-pbryan-zyp-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 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="2011" />
        <area>General</area>
        <workgroup>Internet Engineering Task Force</workgroup>
        <keyword>json</keyword>
        <abstract>
            <t>JSON Pointer defines a syntax for identifying a specific value within a JSON
             document.</t>
        </abstract>
    </front>

    <middle>
        <section title="Introduction">
            <t>This specification defines JSON Pointer, a syntax for identifying a specific
             value within a <xref target="RFC4627">JSON</xref> text document. The syntax is
             intended to be expressed in a JSON string value or the URI fragment identifier of
             a resource that has a JSON representation.</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 syntax rules using
             <xref target="RFC5234">ABNF</xref> (Augmented Backus-Naur Form) notation.
             Additionally, it uses the following rules from
             <xref target="RFC3986">URI syntax</xref>: "unreserved" and "pct-encoded".</t>
        </section>
        <section title="Syntax">
            <t><figure>
            <preamble>A JSON Pointer is a sequence of zero or more reference tokens,
             each prefixed by a "/" (%x2F) character. Each reference token is a sequence of
             unreserved and/or percent-encoded characters, per
            <xref target="RFC3986"/>.</preamble>
            <artwork><![CDATA[
json-pointer = *( "/" reference-token )
reference-token = *( unreserved / pct-encoded )
]]>         </artwork></figure></t>
            <t>Characters in reference tokens that are not unreserved SHOULD be
             percent-encoded, per <xref target="RFC3986"/>, and MUST be so encoded as "%2F" if
             the character is "/" to avoid being interpreted as a reference token prefix.</t>
            <t>It is an error condition if a JSON Pointer does not conform to this syntax.</t>
        </section>
        <section title="Evaluation">
            <t>Evaluation begins with a reference to the root value of a JSON text document,
             and completes with a reference to some value within the same document. Each token
             in the JSON Pointer sequence is evaluated, changing the referenced value according
             to the following scheme:</t>
            <t>If the currently referenced value is a JSON object, the new referenced value is
             the object member with the name identified by the token.</t>
            <t>If the currently referenced value is a JSON array, the 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>
            <t>If a reference token is being evaluated against a concrete JSON text document,
             the implementation MAY evaluate each token against a concrete value, and
             terminate evaluation with an error condition if a reference token fails to resolve
             to a concrete value. If a concrete JSON object contains a referenced member
             with a non-unique name, which of the matching members is resolved is undefined.</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 draft includes no request to IANA.</t>
        </section>

        <section anchor="Security" title="Security Considerations">
            <t>A pointer is not guaranteed to resolve to a JSON value. Implementations of
            JSON Pointer should be aware of this and take appropriate precautions.</t>
        </section>
    </middle>

    <back>
        <references title="Normative References">
          &RFC2119;
          &RFC3986;
          &RFC4627;
          &RFC5234;
        </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>