Diff: rfc7396.original

	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/