One document matched: draft-pbryan-json-patch-04.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-04" 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 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
<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 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" }
]
]]> </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 apply is expressed in a member of the operation object.
The name of the operation member is one of: "add", "remove", "replace", "move"
or "test". The member value is a string containing a
<xref target="JSON Pointer"/>, which references the location in the target
document to apply the operation. It is an error condition if an operation object
contains no operation member, or more than one operation member.</t>
<section title="add">
<t>The "add" operation adds a new value to the target document at the
specified location. 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 in the target document at the
specified location.</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 in the target document at the
specified location 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 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 which references the location in the target document to move 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 identical to expressing a "remove" operation, followed
immediately by an "add" operation at the new location with the value that was
just removed.</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="test">
<t>The "test" operation tests that a value in the target document at the
specified location is equal to a specified value. The operation object
contains a "value" member, which specifies the value to test for.</t>
<figure><preamble>Example:</preamble><artwork><![CDATA[
{ "test": "/a/b/c", value: "foo" }
]]> </artwork></figure>
<t>It is an error condition if the value in the target document 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:"><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 7.</t>
<t hangText="Interoperability considerations:">N/A</t>
<t hangText="Published specification:"><vspace />draft-pbryan-json-patch-04</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 <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>
<section title="Acknowledgements">
<t>The following individuals contributed ideas, feedback and wording, which
contributed to the content of this specification:<list>
<t>Mike Amundsen, Paul Davis, Dean Landolt, Randall Leeds, Mark Nottingham,
Julian Reschke, Eli Stevens.</t>
</list></t>
<t>The structure of a JSON Patch document was initially informed by the
<xref target="RFC5261">XML Patch document</xref> specification.</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="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 04:20:33 |