One document matched: draft-ietf-appsawg-json-patch-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 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-ietf-appsawg-json-patch-01" ipr="trust200902">
<front>
<title>JSON Patch</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>
<date year="2012" />
<area>General</area>
<workgroup>Applications Area Working Group</workgroup>
<keyword>json</keyword>
<abstract>
<t>JSON Patch defines the media type "application/json-patch", a JSON document
structure for expressing a sequence of operations to apply 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 the
<xref target="RFC2616">Hypertext Transfer Protocol (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 operations to apply to a target 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 a
single operation to apply to the target JSON document.</t>
<figure><preamble>An example JSON Patch document:</preamble><artwork><![CDATA[
[
{ "test": "/a/b/c", "value": "foo" },
{ "remove": "/a/b/c" },
{ "add": "/a/b/c", "value": [ "foo", "bar" ] },
{ "replace": "/a/b/c", "value": 42 },
{ "move": "/a/b/c", "to": "/a/b/d" },
{ "copy": "/a/b/c", "to": "/a/b/e" }
]
]]> </artwork></figure>
<t>Evaluation of a JSON Patch document begins with a target JSON document.
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
document becomes the target of the next operation. Evaluation continues until all
operations are successfully applied or an error condition is encountered.</t>
</section>
<section title="Operations">
<t>The operation to perform is expressed in a member of the operation object.
The name of the operation member is one of: "add", "remove", "replace", "move",
"copy" or "test". The member value is a string containing a
<xref target="JSON-Pointer"/> value, which references the location within the
target document to perform the operation. It is an error condition if an operation
object contains no recognized operation member or more than one operation
member.</t>
<section title="add">
<t>The "add" operation adds a new value at the specified location in the
target document. The location must reference one of: the root of the
target document, a member to add to an existing object, or an element to
add to an existing array. The operation object contains a "value" member,
which specifies the value to be added.</t>
<figure><preamble>Example:</preamble><artwork><![CDATA[
{ "add": "/a/b/c", "value": [ "foo", "bar" ] }
]]> </artwork></figure>
<t>If the location references the root of the target document or a member of
an existing object, it is an error condition if a value at the specified
location already exists.</t>
<t>If the location references an element of an existing array, any 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 array.</t>
</section>
<section title="remove">
<t>The "remove" operation removes the value at the specified location in the
target document.</t>
<figure><preamble>Example:</preamble><artwork><![CDATA[
{ "remove": "/a/b/c" }
]]> </artwork></figure>
<t>If removing an element from an array, any elements above the specified
index are shifted one position to the left.</t>
<t>It is an error condition if a value at the specified location does not exist.</t>
</section>
<section title="replace">
<t>The "replace" operation replaces the value at the specified location in the
target document with a new value. The operation object contains a "value"
member, which specifies the replacement value.</t>
<figure><preamble>Example:</preamble><artwork><![CDATA[
{ "replace": "/a/b/c", "value": 42 }
]]> </artwork></figure>
<t>This operation is functionally identical to expressing a "remove" operation
for a value, followed immediately by an "add" operation at the same location
with the replacement value.</t>
<t>It is an error condition if a value at the specified location does not
exist.</t>
</section>
<section title="move">
<t>The "move" operation removes the value at one location and adds it to
another location in the target document.</t>
<t>The operation object contains a "to" member, a string containing a JSON
Pointer value, which references the location in the target document to add
the value to. This location must reference one of: the member to add to an
existing object, or an element to add to an existing array.</t>
<figure><preamble>Example:</preamble><artwork><![CDATA[
{ "move": "/a/b/c", "to": "/a/b/d" }
]]> </artwork></figure>
<t>This operation is functionally identical to expressing a "remove"
operation, followed immediately by an "add" operation at the new location
with the value that was just removed. Moving a value to its current location
can be safely ignored.</t>
<t>If the location in the "to" member references a member of an existing
object in the target document, it is an error condition if a value at the
specified location already exists.</t>
<t>If the location in the "to" member references an element of an existing
array, any 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 array.</t>
</section>
<section title="copy">
<t>The "copy" operation copies the value at one location to another location
in the target document.</t>
<t>The operation object contains a "to" member, a string containing a JSON
Pointer value, which references the location in the target document to add
the value to. This location must reference one of: the member to add to an
existing object, or an element to add to an existing array.</t>
<figure><preamble>Example:</preamble><artwork><![CDATA[
{ "copy": "/a/b/c", "to": "/a/b/e" }
]]> </artwork></figure>
<t>If the location in the "to" member references a member of an existing
object in the target document, it is an error condition if a value at the
specified location already exists.</t>
<t>If the location in the "to" member references an element of an existing
array, any 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 array.</t>
</section>
<section title="test">
<t>The "test" operation tests that a value at the specified location in the
target document is equal to a specified value. The operation object
contains a "value" member, which specifies the value to test for.
If values are or contain objects or arrays, they must be identical (i.e. same
order of elements, with the same values).</t>
<figure><preamble>Example:</preamble><artwork><![CDATA[
{ "test": "/a/b/c", "value": "foo" }
]]> </artwork></figure>
<t>It is an error condition if the value at the specified location is not
equal to the specified value.</t>
</section>
</section>
<section anchor="Errors" title="Error Handling">
<t>If an error condition occurs, evaluation of the JSON Patch document SHOULD
terminate and application of the entire patch document SHALL NOT be deemed
successful.</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:"> binary</t>
<t hangText="Security considerations:"><vspace />
See Security Considerations in section 7.</t>
<t hangText="Interoperability considerations:">N/A</t>
<t hangText="Published specification:"><vspace />[this memo]</t>
<t hangText="Applications that use this media type:"><vspace />
Applications that manipulate JSON documents.</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 <pbryan@anode.ca></t>
<t hangText="Intended usage:">COMMON</t>
<t hangText="Restrictions on usage:">none</t>
<t hangText="Author:">Paul C. Bryan <pbryan@anode.ca></t>
<t hangText="Change controller:">IETF</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"/>.</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, Mike Amundsen, Paul Davis, Murray S. Kucherawy, Dean Landolt,
Randall Leeds, Mark Nottingham, Julian Reschke, Eli Stevens.</t>
</list></t>
<t>The structure of a JSON Patch document was influenced by the
<xref target="RFC5261">XML Patch document</xref> specification.</t>
</section>
</middle>
<back>
<references title="Normative References">
&RFC2119;
&RFC4627;
<reference anchor="JSON-Pointer">
<front>
<title>JSON Pointer</title>
<author initials="P." surname="Bryan" fullname="Paul C. Bryan">
<organization>ForgeRock</organization>
</author>
<author initials="K." surname="Zyp" fullname="Kris Zyp">
<organization>SitePen (USA)</organization>
</author>
<date year="2012" month="March"/>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-appsawg-json-pointer-01"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-appsawg-json-pointer-01.txt"/>
<format type="HTML" target="http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-01"/>
</reference>
</references>
<references title="Informative References">
&RFC2616;
&RFC5261;
&RFC5789;
</references>
<section title="Examples">
<section anchor="add-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="add-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="remove-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="remove-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="replace-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 anchor="move-value" title="Moving a Value">
<t>An example target JSON document:</t>
<figure>
<artwork><![CDATA[
{
"foo": {
"bar": "baz",
"waldo": "fred"
}
"qux": {
"corge": "grault"
}
}
]]> </artwork>
</figure>
<t>A JSON Patch document:</t>
<figure>
<artwork><![CDATA[
[
{ "move": "/foo/waldo", to: "/qux/thud" }
]
]]> </artwork>
</figure>
<t>The resulting JSON document:</t>
<figure>
<artwork><![CDATA[
{
"foo": {
"bar": "baz"
}
"qux": {
"corge": "grault",
"thud": "fred"
}
}
]]> </artwork>
</figure>
</section>
<section anchor="move-element" title="Moving an Array Element">
<t>An example target JSON document:</t>
<figure>
<artwork><![CDATA[
{
"foo": [ "all", "grass", "cows", "eat" ]
}
]]> </artwork>
</figure>
<t>A JSON Patch document:</t>
<figure>
<artwork><![CDATA[
[
{ "move": "/foo/1", "to": "/foo/3" }
]
]]> </artwork>
</figure>
<t>The resulting JSON document:</t>
<figure>
<artwork><![CDATA[
{
"foo": [ "all", "cows", "eat", "grass" ]
}
]]> </artwork>
</figure>
</section>
<section anchor="test-success" title="Testing a Value: Success">
<t>An example target JSON document:</t>
<figure>
<artwork><![CDATA[
{
"baz": "qux",
"foo": [ "a", 2, "c" ]
}
]]> </artwork>
</figure>
<t>A JSON Patch document, which will result in successful evaluation:</t>
<figure>
<artwork><![CDATA[
[
{ "test": "/baz", "value": "qux" },
{ "test": "/foo/1", "value": 2 }
]
]]> </artwork>
</figure>
</section>
<section anchor="test-error" title="Testing a Value: Error">
<t>An example target JSON document:</t>
<figure>
<artwork><![CDATA[
{
"baz": "qux"
}
]]> </artwork>
</figure>
<t>A JSON Patch document, which will result in an error condition:</t>
<figure>
<artwork><![CDATA[
[
{ "test": "/baz", "value": "bar" }
]
]]> </artwork>
</figure>
</section>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 06:42:29 |