One document matched: draft-pbryan-json-patch-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 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 RFC5261 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5261.xml">
<!ENTITY RFC5789 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5789.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-json-patch-02" ipr="trust200902">

    <front>
        <title>JSON Patch</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>
        <date year="2011" />
        <area>General</area>
        <workgroup>Internet Engineering Task Force</workgroup>
        <keyword>json</keyword>
        <abstract>
            <t>JSON Patch defines the media type "application/json-patch", a JSON document
             structure for expressing a sequence of partial modifications to a JSON
             document.</t> 
        </abstract>
    </front>

    <middle>

        <section title="Introduction">
            <t><xref target="RFC4627">JavaScript Object Notation (JSON)</xref> is a common
             format for the exchange and storage of structured data.
             <xref target="RFC5789">HTTP PATCH</xref> extends
             <xref target="RFC2616">HTTP</xref> with a method to perform partial modifications
             to resources.</t>
            <t>The JSON Patch media type "application/json-patch" is a JSON document structure
             for expressing a sequence of partial modifications to a JSON document, suitable
             for use with the HTTP PATCH method.</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">RFC 2119</xref>.</t>
        </section>

        <section anchor="Structure" title="Document Structure">

            <t>A JSON Patch document contains a JSON array of objects. Each object contains an
             operation to apply to the target JSON document.</t>

            <figure><preamble>A sample JSON Patch document:</preamble><artwork><![CDATA[
[
    { "remove": "/a/b/c" },
    { "add": "/a/b/c", "value": "foo" },
    { "replace": "/a/b/c", "value": "bar" }
]
]]>         </artwork></figure>
            <t>Evaluation of a JSON Patch document begins with a target JSON document to
             modify. Operations are applied sequentially in the order they appear in the
             array. Each operation in the sequence is applied to the target document. The
             resulting modified document becomes the target for the next operation. The
             process repeats until all operations are successfully applied.</t>
        </section>

        <section title="Operations">

            <t>The operation to perform is expressed in the name of a member in the operation
             object, with that member's value holding a string containing the
             <xref target="JSON Pointer"/>, which references the value to modify. It is an
             error condition if an operation object contains more than one operation
             member.</t>

            <section title="add">
                <t>The "add" operation adds a new value into an object or array. The value to be
                 added is specified in the operation object's "value" member.</t>
                <t>If adding to an object, it is an error condition if the member to be added
                 in the object already exists.</t>
                <t>If adding to an array, all elements at or above the specified index are
                 shifted one position to the right. It is an error condition if the specified
                 index is greater than the number of elements in the existing array.</t>
            </section>

            <section title="remove">
                <t>The "remove" operation removes a value from an object or array.</t>
                <t>If removing an element from an array, all elements above the specified
                 index are shifted one position to the left.</t>
                <t>It is an error condition if the value to be removed does not exist.</t>
            </section>

            <section title="replace">
                <t>The "replace" operation replaces an existing value with a new value. This
                 operation is equivalent to expressing a "remove" operation for a value,
                 followed immediately by an "add" operation for the same value. The value to
                 be replaced is specified in the operation object's "value" member.</t>
                <t>It is an error condition if the value to be replaced does not exist.</t> 
            </section>

        </section>
        
        <section anchor="Errors" title="Error Handling">
            <t>In the event of an error condition, evaluation of the JSON Patch document
             terminates and modification of the target document fails to complete.</t>
        </section>

        <section title="Acknowledgements">
            <t>The structure of a JSON Patch document was informed by the
             <xref target="RFC5261">XML Patch document</xref> specification.</t>
        </section>

        <section anchor="IANA" title="IANA Considerations">
            <t>The Internet media type for a JSON Patch document is application/json-patch.
            <list style="hanging">
            <t hangText="Type name:">application</t>
            <t hangText="Subtype name:">json-patch</t>
            <t hangText="Required parameters:">none</t>
            <t hangText="Optional parameters: ">none</t>
            <t hangText="Encoding considerations:"><vspace />Per
             <xref target="RFC4627">JSON</xref>: 8bit if UTF-8; binary if UTF-16 or UTF-32.</t>
            <t hangText="Security considerations:"><vspace />See Security Considerations in
             section 8.</t>
            <t hangText="Interoperability considerations:">N/A</t>
            <t hangText="Published specification:"><vspace />draft-pbryan-json-patch-02</t>
            <t hangText="Applications that use this media type:"><vspace />
             HTTP clients and servers.</t>
            <t hangText="Additional information:"><list>
                <t hangText="Magic number(s):">N/A</t>
                <t hangText="File extension(s):">.json-patch</t>
                <t hangText="Macintosh file type code(s):">TEXT</t>
             </list></t>
            <t hangText="Person & email address to contact for further information:">
             <vspace />Paul C. Bryan <paul.bryan@forgerock.com></t>
            <t hangText="Intended usage:">COMMON</t>
            <t hangText="Restrictions on usage:">none</t>
            <t hangText="Author:">Paul C. Bryan <paul.bryan@forgerock.com></t>
            <t hangText="Change controller:">Paul C. Bryan <paul.bryan@forgerock.com></t>
            </list></t>
        </section>

        <section anchor="Security" title="Security Considerations">
            <t>This specification has the same security considerations as
             <xref target="RFC4627">JSON</xref> and
             <xref target="JSON Pointer">JSON Pointer</xref>.</t>
        </section>

    </middle>

    <back>
        <references title="Normative References">
          &RFC2119;
          &RFC4627;
          <reference anchor="JSON Pointer" target="http://tools.ietf.org/html/draft-pbryan-zyp-json-pointer-02">
            <front>
                <title>JSON Pointer</title>
                <author initials="P." surname="Bryan">
                    <organization>ForgeRock US, Inc.</organization>
                </author>
                <author initials="K." surname="Zyp">
                    <organization>SitePen (USA)</organization>
                </author>
                <date year="2011" month="October" />
            </front>
            </reference>
        </references>

        <references title="Informative References">
          &RFC2616;
          &RFC5261;
          &RFC5789;
        </references>

        <section title="Examples">
            <section anchor="Adding-Member" title="Adding an Object Member">
                <t>An example target JSON document:</t>
                <figure>
                    <artwork><![CDATA[
{
    "foo": "bar"
}
]]>                 </artwork>
                </figure>
                <t>A JSON Patch document:</t>
                <figure>
                    <artwork><![CDATA[
[
    { "add": "/baz", "value": "qux" }
]
]]>                 </artwork>
                </figure>
                <t>The resulting JSON document:</t>
                <figure>
                    <artwork><![CDATA[
{
    "baz": "qux",
    "foo": "bar"
}
]]>                 </artwork>
                </figure>
            </section>
            <section anchor="Adding-Element" title="Adding an Array Element">
                <t>An example target JSON document:</t>
                <figure>
                    <artwork><![CDATA[
{
    "foo": [ "bar", "baz" ]
}
]]>                 </artwork>
                </figure>
                <t>A JSON Patch document:</t>
                <figure>
                    <artwork><![CDATA[
[
    { "add": "/foo/1", "value": "qux" }
]
]]>                 </artwork>
                </figure>
                <t>The resulting JSON document:</t>
                <figure>
                    <artwork><![CDATA[
{
    "foo": [ "bar", "qux", "baz" ]
}
]]>                 </artwork>
                </figure>
            </section>
            <section anchor="Removing-Member" title="Removing an Object Member">
                <t>An example target JSON document:</t>
                <figure>
                    <artwork><![CDATA[
{
    "baz": "qux",
    "foo": "bar"
}
]]>                 </artwork>
                </figure>
                <t>A JSON Patch document:</t>
                <figure>
                    <artwork><![CDATA[
[
    { "remove": "/baz" }
]
]]>                 </artwork>
                </figure>
                <t>The resulting JSON document:</t>
                <figure>
                    <artwork><![CDATA[
{
    "foo": "bar"
}
]]>                 </artwork>
                </figure>
            </section>
            <section anchor="Removing-Element" title="Removing an Array Element">
                <t>An example target JSON document:</t>
                <figure>
                    <artwork><![CDATA[
{
    "foo": [ "bar", "qux", "baz" ]
}
]]>                 </artwork>
                </figure>
                <t>A JSON Patch document:</t>
                <figure>
                    <artwork><![CDATA[
[
    { "remove": "/foo/1" }
]
]]>                 </artwork>
                </figure>
                <t>The resulting JSON document:</t>
                <figure>
                    <artwork><![CDATA[
{
    "foo": ["bar", "baz"]
}
]]>                 </artwork>
                </figure>
            </section>
            <section anchor="Replacing-Value" title="Replacing a Value">
                <t>An example target JSON document:</t>
                <figure>
                    <artwork><![CDATA[
{
    "baz": "qux",
    "foo": "bar"
}
]]>                 </artwork>
                </figure>
                <t>A JSON Patch document:</t>
                <figure>
                    <artwork><![CDATA[
[
      { "replace": "/baz", "value": "boo" }
]
]]>                 </artwork>
                </figure>
                <t>The resulting JSON document:</t>
                <figure>
                    <artwork><![CDATA[
{
    "baz": "boo",
    "foo": "bar"
}
]]>                 </artwork>
                </figure>
            </section>
        </section>
        
    </back>

</rfc>