rfc7396.original   rfc7396.txt 
Internet Engineering Task Force (IETF) P. Hoffman Internet Engineering Task Force (IETF) P. Hoffman
Request for Comments: 7386 VPN Consortium Request for Comments: 7396 VPN Consortium
Category: Standards Track J. Snell Obsoletes: 7386 J. Snell
Category: Standards Track
ISSN: 2070-1721 October 2014 ISSN: 2070-1721 October 2014
JSON Merge Patch JSON Merge Patch
Abstract Abstract
This specification defines the JSON merge patch format and processing This specification defines the JSON merge patch format and processing
rules. The merge patch format is primarily intended for use with the rules. The merge patch format is primarily intended for use with the
HTTP PATCH method as a means of describing a set of modifications to HTTP PATCH method as a means of describing a set of modifications to
a target resource's content. a target resource's content.
skipping to change at page 1, line 29 skipping to change at page 1, line 30
This is an Internet Standards Track document. This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has (IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741. Internet Standards is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata, Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc7386. http://www.rfc-editor.org/info/rfc7396.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 40 skipping to change at page 2, line 40
set of changes being requested by comparing the content of the set of changes being requested by comparing the content of the
provided patch against the current content of the target document. provided patch against the current content of the target document.
If the provided merge patch contains members that do not appear If the provided merge patch contains members that do not appear
within the target, those members are added. If the target does within the target, those members are added. If the target does
contain the member, the value is replaced. Null values in the merge contain the member, the value is replaced. Null values in the merge
patch are given special meaning to indicate the removal of existing patch are given special meaning to indicate the removal of existing
values in the target. values in the target.
For example, given the following original JSON document: For example, given the following original JSON document:
{ {
"a": "b", "a": "b",
"c": { "c": {
"d": "e", "d": "e",
"f": "g" "f": "g"
} }
} }
Changing the value of "a" and removing "f" can be achieved by Changing the value of "a" and removing "f" can be achieved by
sending: sending:
PATCH /target HTTP/1.1 PATCH /target HTTP/1.1
Host: example.org Host: example.org
Content-Type: application/merge-patch+json Content-Type: application/merge-patch+json
{ {
"a":"z", "a":"z",
"c": { "c": {
"f": null "f": null
} }
} }
When applied to the target resource, the value of the "a" member is When applied to the target resource, the value of the "a" member is
replaced with "z" and "f" is removed, leaving the remaining content replaced with "z" and "f" is removed, leaving the remaining content
untouched. untouched.
This design means that merge patch documents are suitable for This design means that merge patch documents are suitable for
describing modifications to JSON documents that primarily use objects describing modifications to JSON documents that primarily use objects
for their structure and do not make use of explicit null values. The for their structure and do not make use of explicit null values. The
merge patch format is not appropriate for all JSON syntaxes. merge patch format is not appropriate for all JSON syntaxes.
skipping to change at page 4, line 5 skipping to change at page 4, line 5
current content of the target resource to determine the specific set current content of the target resource to determine the specific set
of change operations to be applied to the target. of change operations to be applied to the target.
To apply the merge patch document to a target resource, the system To apply the merge patch document to a target resource, the system
realizes the effect of the following function, described in realizes the effect of the following function, described in
pseudocode. For this description, the function is called MergePatch, pseudocode. For this description, the function is called MergePatch,
and it takes two arguments: the target resource document and the and it takes two arguments: the target resource document and the
merge patch document. The Target argument can be any JSON value or merge patch document. The Target argument can be any JSON value or
undefined. The Patch argument can be any JSON value. undefined. The Patch argument can be any JSON value.
define MergePatch(Target, Patch): define MergePatch(Target, Patch):
if Patch is an Object: if Patch is an Object:
if Target is not an Object: if Target is not an Object:
Target = {} # Ignore the contents and set it to an empty Object Target = {} # Ignore the contents and set it to an empty Object
for each Name/Value pair in Patch: for each Name/Value pair in Patch:
if Value is null: if Value is null:
if Name exists in Target: if Name exists in Target:
remove the Name/Value pair from Target remove the Name/Value pair from Target
else: else:
Target[Name] = MergePatch(Target[Name], Value) Target[Name] = MergePatch(Target[Name], Value)
return Target return Target
else: else:
return Patch return Patch
There are a few things to note about the function. If the patch is There are a few things to note about the function. If the patch is
anything other than an object, the result will always be to replace anything other than an object, the result will always be to replace
the entire target with the entire patch. Also, it is not possible to the entire target with the entire patch. Also, it is not possible to
patch part of a target that is not an object, such as to replace just patch part of a target that is not an object, such as to replace just
some of the values in an array. some of the values in an array.
The MergePatch operation is defined to operate at the level of data The MergePatch operation is defined to operate at the level of data
items, not at the level of textual representation. There is no items, not at the level of textual representation. There is no
expectation that the MergePatch operation will preserve features at expectation that the MergePatch operation will preserve features at
skipping to change at page 4, line 39 skipping to change at page 4, line 39
ordering, number precision beyond what is available in the target's ordering, number precision beyond what is available in the target's
implementation, and so forth. In addition, even if the target implementation, and so forth. In addition, even if the target
implementation allows multiple name/value pairs with the same name, implementation allows multiple name/value pairs with the same name,
the result of the MergePatch operation on such objects is not the result of the MergePatch operation on such objects is not
defined. defined.
3. Example 3. Example
Given the following example JSON document: Given the following example JSON document:
{ {
"title": "Goodbye!", "title": "Goodbye!",
"author" : { "author" : {
"givenName" : "John", "givenName" : "John",
"familyName" : "Doe" "familyName" : "Doe"
}, },
"tags":[ "example", "sample" ], "tags":[ "example", "sample" ],
"content": "This will be unchanged" "content": "This will be unchanged"
} }
A user agent wishing to change the value of the "title" member from A user agent wishing to change the value of the "title" member from
"Goodbye!" to the value "Hello!", add a new "phoneNumber" member, "Goodbye!" to the value "Hello!", add a new "phoneNumber" member,
remove the "familyName" member from the "author" object, and replace remove the "familyName" member from the "author" object, and replace
the "tags" array so that it doesn't include the word "sample" would the "tags" array so that it doesn't include the word "sample" would
send the following request: send the following request:
PATCH /my/resource HTTP/1.1 PATCH /my/resource HTTP/1.1
Host: example.org Host: example.org
Content-Type: application/merge-patch+json Content-Type: application/merge-patch+json
{ {
"title": "Hello!", "title": "Hello!",
"phoneNumber": "+01-123-456-7890", "phoneNumber": "+01-123-456-7890",
"author": { "author": {
"familyName": null "familyName": null
}, },
"tags": [ "example" ] "tags": [ "example" ]
} }
The resulting JSON document would be: The resulting JSON document would be:
{ {
"title": "Hello!", "title": "Hello!",
"author" : { "author" : {
"givenName" : "John" "givenName" : "John"
}, },
"tags": [ "example" ], "tags": [ "example" ],
"content": "This will be unchanged", "content": "This will be unchanged",
"phoneNumber": "+01-123-456-7890" "phoneNumber": "+01-123-456-7890"
} }
4. IANA Considerations 4. IANA Considerations
This specification registers the following additional MIME media This specification registers the following additional MIME media
types: types:
Type name: application Type name: application
Subtype name: merge-patch+json Subtype name: merge-patch+json
 End of changes. 15 change blocks. 
56 lines changed or deleted 55 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/