Diff: rfc7386.original

	rfc7386.original	rfc7396.txt


	Applications Area Working Group P. Hoffman	Internet Engineering Task Force (IETF) P. Hoffman
	Internet-Draft VPN Consortium	Request for Comments: 7396 VPN Consortium
	Intended status: Standards Track J. Snell	Obsoletes: 7386 J. Snell
	Expires: February 22, 2015	Category: Standards Track
	August 21, 2014	ISSN: 2070-1721 October 2014

	JSON Merge Patch	JSON Merge Patch

	draft-ietf-appsawg-json-merge-patch-07

	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.

	Status of This Memo	Status of This Memo


	This Internet-Draft is submitted in full conformance with the	This is an Internet Standards Track document.
	provisions of BCP 78 and BCP 79.

	Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF). Note that other groups may also distribute
	working documents as Internet-Drafts. The list of current Internet-
	Drafts is at http://datatracker.ietf.org/drafts/current/.


	Internet-Drafts are draft documents valid for a maximum of six months	This document is a product of the Internet Engineering Task Force
	and may be updated, replaced, or obsoleted by other documents at any	(IETF). It represents the consensus of the IETF community. It has
	time. It is inappropriate to use Internet-Drafts as reference	received public review and has been approved for publication by the
	material or to cite them other than as "work in progress."	Internet Engineering Steering Group (IESG). Further information on
		Internet Standards is available in Section 2 of RFC 5741.


	This Internet-Draft will expire on February 22, 2015.	Information about the current status of this document, any errata,
		and how to provide feedback on it may be obtained at
		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 12	skipping to change at page 2, line 12
	the Trust Legal Provisions and are provided without warranty as	the Trust Legal Provisions and are provided without warranty as
	described in the Simplified BSD License.	described in the Simplified BSD License.

	Table of Contents	Table of Contents

	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
	2. Processing Merge Patch Documents . . . . . . . . . . . . . . 3	2. Processing Merge Patch Documents . . . . . . . . . . . . . . 3
	3. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 4	3. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
	4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5	4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5
	5. Security Considerations . . . . . . . . . . . . . . . . . . . 6	5. Security Considerations . . . . . . . . . . . . . . . . . . . 6

	6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6	6. References . . . . . . . . . . . . . . . . . . . . . . . . . 7
	7. References . . . . . . . . . . . . . . . . . . . . . . . . . 6	6.1. Normative References . . . . . . . . . . . . . . . . . . 7
	7.1. Normative References . . . . . . . . . . . . . . . . . . 6	6.2. Informative References . . . . . . . . . . . . . . . . . 7
	7.2. Informative References . . . . . . . . . . . . . . . . . 7	Appendix A. Example Test Cases . . . . . . . . . . . . . . . . . 8
	Appendix A. Example Test Cases . . . . . . . . . . . . . . . . . 7	Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 9
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9

	1. Introduction	1. Introduction

	This specification defines the JSON merge patch document format,	This specification defines the JSON merge patch document format,
	processing rules, and associated MIME media type identifier. The	processing rules, and associated MIME media type identifier. The
	merge patch format is primarily intended for use with the HTTP PATCH	merge patch format is primarily intended for use with the HTTP PATCH
	method [RFC5789] as a means of describing a set of modifications to a	method [RFC5789] as a means of describing a set of modifications to a
	target resource's content.	target resource's content.


	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 3, line 40	skipping to change at page 3, line 39
	JSON merge patch documents describe, by example, a set of changes	JSON merge patch documents describe, by example, a set of changes
	that are to be made to a target resource. Recipients of merge patch	that are to be made to a target resource. Recipients of merge patch
	documents are responsible for comparing the merge patch with the	documents are responsible for comparing the merge patch with the
	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 if 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 textual	expectation that the MergePatch operation will preserve features at
	representation-level features such as white space, member ordering,	the textual-representation level such as white space, member
	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 patch operation on such objects is not defined.	the result of the MergePatch operation on such objects is not
		defined.

	3. Example	3. Example


	For example, given the following example JSON document:	Given the following example JSON document:

	{
	"title": "Goodbye!",
	"author" : {
	"givenName" : "John",
	"familyName" : "Doe"
	},
	"tags":[ "example", "sample" ],
	"content": "This will be unchanged"
	}


	A user-agent wishing to change the value of the "title" member from	{
		"title": "Goodbye!",
		"author" : {
		"givenName" : "John",
		"familyName" : "Doe"
		},
		"tags":[ "example", "sample" ],
		"content": "This will be unchanged"
		}
		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

	Required parameters: None	Required parameters: None

	Optional parameters: None	Optional parameters: None

	Encoding considerations: Resources that use the "application/	Encoding considerations: Resources that use the "application/
	merge-patch+json" media type are required to conform to the	merge-patch+json" media type are required to conform to the

	"application/json" Media Type and are therefore subject to the	"application/json" media type and are therefore subject to the
	same encoding considerations specified in Section 8 of [RFC7159].	same encoding considerations specified in Section 8 of [RFC7159].

	Security considerations: As defined in this specification	Security considerations: As defined in this specification

	Published specification: This specification.	Published specification: This specification.

	Applications that use this media type: None currently known.	Applications that use this media type: None currently known.

	Additional information:	Additional information:

	Magic number(s): N/A	Magic number(s): N/A

	File extension(s): N/A	File extension(s): N/A

	Macintosh file type code(s): TEXT	Macintosh file type code(s): TEXT

	Person & email address to contact for further information: IESG	Person & email address to contact for further information: IESG

	Intended usage: COMMON	Intended usage: COMMON


	Restrictions on usage: None.	Restrictions on usage: None


	Author: James M Snell <jasnell@gmail.com>	Author: James M. Snell <jasnell@gmail.com>

	Change controller: IESG	Change controller: IESG

	5. Security Considerations	5. Security Considerations


	The "application/merge-patch+json" Media Type allows user agents to	The "application/merge-patch+json" media type allows user agents to
	indicate their intention that the server determine the specific set	indicate their intention for the server to determine the specific set
	of change operations to be applied to a target resource. As such, it	of change operations to be applied to a target resource. As such, it
	is the server's responsibility to determine the appropriateness of	is the server's responsibility to determine the appropriateness of
	any given change as well as the user agent's authorization to request	any given change as well as the user agent's authorization to request
	such changes. How such determinations are made is considered out of	such changes. How such determinations are made is considered out of
	the scope of this specification.	the scope of this specification.


	All of the the security considerations discussed in Section 5 of	All of the security considerations discussed in Section 5 of
	[RFC5789] apply to all uses of the HTTP PATCH method with the	[RFC5789] apply to all uses of the HTTP PATCH method with the

	"application/merge-patch+json" Media Type.	"application/merge-patch+json" media type.

	6. Acknowledgements

	Many people contributed significant ideas to this document. These
	people include, but are not limited to, James Manger, Matt Miller,
	Carsten Bormann, and Bjoern Hoehrmann, Pete Resnick, and Richard
	Barnes.


	7. References	6. References


	7.1. Normative References	6.1. Normative References

	[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data	[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data

	Interchange Format", RFC 7159, March 2014.	Interchange Format", RFC 7159, March 2014,
		<http://www.rfc-editor.org/info/rfc7159>.


	7.2. Informative References	6.2. Informative References

	[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC	[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC

	5789, March 2010.	5789, March 2010,
		<http://www.rfc-editor.org/info/rfc5789>.

	Appendix A. Example Test Cases	Appendix A. Example Test Cases


	ORIGINAL PATCH RESULT	ORIGINAL PATCH RESULT
	------------------------------------------	------------------------------------------
	{"a":"b"} {"a":"c"} {"a":"c"}	{"a":"b"} {"a":"c"} {"a":"c"}

	{"a":"b"} {"b":"c"} {"a":"b",	{"a":"b"} {"b":"c"} {"a":"b",
	"b":"c"}	"b":"c"}

	{"a":"b"} {"a":null} {}	{"a":"b"} {"a":null} {}

	{"a":"b", {"a":null} {"b":"c"}	{"a":"b", {"a":null} {"b":"c"}

	skipping to change at page 9, line 5	skipping to change at page 9, line 5
	"a":1}	"a":1}

	[1,2] {"a":"b", {"a":"b"}	[1,2] {"a":"b", {"a":"b"}
	"c":null}	"c":null}

	{} {"a": {"a":	{} {"a": {"a":
	{"bb": {"bb":	{"bb": {"bb":
	{"ccc": {}}}	{"ccc": {}}}
	null}}}	null}}}


		Acknowledgments

		Many people contributed significant ideas to this document. These
		people include, but are not limited to, James Manger, Matt Miller,
		Carsten Bormann, Bjoern Hoehrmann, Pete Resnick, and Richard Barnes.

	Authors' Addresses	Authors' Addresses

	Paul Hoffman	Paul Hoffman
	VPN Consortium	VPN Consortium


	Email: paul.hoffman@vpnc.org	EMail: paul.hoffman@vpnc.org


	James M Snell	James M. Snell


	Email: jasnell@gmail.com	EMail: jasnell@gmail.com

End of changes. 38 change blocks.
	100 lines changed or deleted	97 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/