< draft-ietf-appsawg-json-patch-03.txt		draft-ietf-appsawg-json-patch-04.txt >
	Applications Area Working Group P. Bryan, Ed.		Applications Area Working Group P. Bryan, Ed.
	Internet-Draft Salesforce.com		Internet-Draft Salesforce.com
	Intended status: Informational M. Nottingham, Ed.		Intended status: Informational M. Nottingham, Ed.
	Expires: March 9, 2013 September 5, 2012		Expires: March 21, 2013 September 17, 2012
	JSON Patch		JSON Patch
	draft-ietf-appsawg-json-patch-03		draft-ietf-appsawg-json-patch-04
	Abstract		Abstract
	JSON Patch defines the media type "application/json-patch", a JSON		JSON Patch defines the media type "application/json-patch", a JSON
	document structure for expressing a sequence of operations to apply		document structure for expressing a sequence of operations to apply
	to a JSON document.		to a JSON document.
	Status of this Memo		Status of this Memo
	This Internet-Draft is submitted in full conformance with the		This Internet-Draft is submitted in full conformance with the
	skipping to change at page 1, line 32 ¶		skipping to change at page 1, line 32 ¶
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF). Note that other groups may also distribute		Task Force (IETF). Note that other groups may also distribute
	working documents as Internet-Drafts. The list of current Internet-		working documents as Internet-Drafts. The list of current Internet-
	Drafts is at http://datatracker.ietf.org/drafts/current/.		Drafts is at http://datatracker.ietf.org/drafts/current/.
	Internet-Drafts are draft documents valid for a maximum of six months		Internet-Drafts are draft documents valid for a maximum of six months
	and may be updated, replaced, or obsoleted by other documents at any		and may be updated, replaced, or obsoleted by other documents at any
	time. It is inappropriate to use Internet-Drafts as reference		time. It is inappropriate to use Internet-Drafts as reference
	material or to cite them other than as "work in progress."		material or to cite them other than as "work in progress."
	This Internet-Draft will expire on March 9, 2013.		This Internet-Draft will expire on March 21, 2013.
	Copyright Notice		Copyright Notice
	Copyright (c) 2012 IETF Trust and the persons identified as the		Copyright (c) 2012 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 18 ¶		skipping to change at page 2, line 18 ¶
	2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 3		2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 3
	3. Document Structure . . . . . . . . . . . . . . . . . . . . . . 3		3. Document Structure . . . . . . . . . . . . . . . . . . . . . . 3
	4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 3		4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 3
	4.1. add . . . . . . . . . . . . . . . . . . . . . . . . . . . 4		4.1. add . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
	4.2. remove . . . . . . . . . . . . . . . . . . . . . . . . . . 4		4.2. remove . . . . . . . . . . . . . . . . . . . . . . . . . . 4
	4.3. replace . . . . . . . . . . . . . . . . . . . . . . . . . 5		4.3. replace . . . . . . . . . . . . . . . . . . . . . . . . . 5
	4.4. move . . . . . . . . . . . . . . . . . . . . . . . . . . . 5		4.4. move . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
	4.5. copy . . . . . . . . . . . . . . . . . . . . . . . . . . . 6		4.5. copy . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
	4.6. test . . . . . . . . . . . . . . . . . . . . . . . . . . . 6		4.6. test . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
	5. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 7		5. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 7
	6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7		6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
	7. Security Considerations . . . . . . . . . . . . . . . . . . . 8		7. Security Considerations . . . . . . . . . . . . . . . . . . . 9
	8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 8		8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9
	9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9		9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9
	9.1. Normative References . . . . . . . . . . . . . . . . . . . 9		9.1. Normative References . . . . . . . . . . . . . . . . . . . 9
	9.2. Informative References . . . . . . . . . . . . . . . . . . 9		9.2. Informative References . . . . . . . . . . . . . . . . . . 9
	Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 9		Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 10
	A.1. Adding an Object Member . . . . . . . . . . . . . . . . . 9		A.1. Adding an Object Member . . . . . . . . . . . . . . . . . 10
	A.2. Adding an Array Element . . . . . . . . . . . . . . . . . 10		A.2. Adding an Array Element . . . . . . . . . . . . . . . . . 10
	A.3. Removing an Object Member . . . . . . . . . . . . . . . . 10		A.3. Removing an Object Member . . . . . . . . . . . . . . . . 11
	A.4. Removing an Array Element . . . . . . . . . . . . . . . . 11		A.4. Removing an Array Element . . . . . . . . . . . . . . . . 11
	A.5. Replacing a Value . . . . . . . . . . . . . . . . . . . . 11		A.5. Replacing a Value . . . . . . . . . . . . . . . . . . . . 12
	A.6. Moving a Value . . . . . . . . . . . . . . . . . . . . . . 11		A.6. Moving a Value . . . . . . . . . . . . . . . . . . . . . . 12
	A.7. Moving an Array Element . . . . . . . . . . . . . . . . . 12		A.7. Moving an Array Element . . . . . . . . . . . . . . . . . 13
	A.8. Testing a Value: Success . . . . . . . . . . . . . . . . . 13		A.8. Testing a Value: Success . . . . . . . . . . . . . . . . . 13
	A.9. Testing a Value: Error . . . . . . . . . . . . . . . . . . 13		A.9. Testing a Value: Error . . . . . . . . . . . . . . . . . . 14
	A.10. Adding a nested Member Object . . . . . . . . . . . . . . 13		A.10. Adding a nested Member Object . . . . . . . . . . . . . . 14
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 14		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 14
	1. Introduction		1. Introduction
	JavaScript Object Notation (JSON) [RFC4627] is a common format for		JavaScript Object Notation (JSON) [RFC4627] is a common format for
	the exchange and storage of structured data. HTTP PATCH [RFC5789]		the exchange and storage of structured data. HTTP PATCH [RFC5789]
	extends the Hypertext Transfer Protocol (HTTP) [RFC2616] with a		extends the Hypertext Transfer Protocol (HTTP) [RFC2616] with a
	method to perform partial modifications to resources.		method to perform partial modifications to resources.
	The JSON Patch media type "application/json-patch" is a JSON document		The JSON Patch media type "application/json-patch" is a JSON document
	skipping to change at page 4, line 38 ¶		skipping to change at page 4, line 38 ¶
	the right. It is an error condition if the specified index is		the right. It is an error condition if the specified index is
	greater than the number of elements in the array.		greater than the number of elements in the array.
	Note that this operation will, in common use, contain a JSON Pointer		Note that this operation will, in common use, contain a JSON Pointer
	that does not resolve to an existing value in the target document.		that does not resolve to an existing value in the target document.
	As such, the pointer's error handling algorithm is invoked. This		As such, the pointer's error handling algorithm is invoked. This
	specification defines the error handling algorithm for "add" pointers		specification defines the error handling algorithm for "add" pointers
	to explicitly ignore the error and perform the operation as		to explicitly ignore the error and perform the operation as
	specified.		specified.
			It is an error condition if the "value" member is not present.
	4.2. remove		4.2. remove
	The "remove" operation removes the value at the specified location in		The "remove" operation removes the value at the specified location in
	the target document.		the target document.
	Example:		Example:
	{ "remove": "/a/b/c" }		{ "remove": "/a/b/c" }
	If removing an element from an array, any elements above the		If removing an element from an array, any elements above the
	skipping to change at page 5, line 22 ¶		skipping to change at page 5, line 23 ¶
	{ "replace": "/a/b/c", "value": 42 }		{ "replace": "/a/b/c", "value": 42 }
	This operation is functionally identical to expressing a "remove"		This operation is functionally identical to expressing a "remove"
	operation for a value, followed immediately by an "add" operation at		operation for a value, followed immediately by an "add" operation at
	the same location with the replacement value.		the same location with the replacement value.
	It is an error condition if a value at the specified location does		It is an error condition if a value at the specified location does
	not exist.		not exist.
			It is an error condition if the "value" member is not present.
	4.4. move		4.4. move
	The "move" operation removes the value at one location and adds it to		The "move" operation removes the value at one location and adds it to
	another location in the target document.		another location in the target document.
	The operation object contains a "to" member, a string containing a		The operation object contains a "to" member, a string containing a
	JSON Pointer value that references the location in the target		JSON Pointer value that references the location in the target
	document to add the value to. This location must reference one of:		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		the member to add to an existing object, or an element to add to an
	existing array.		existing array.
	skipping to change at page 6, line 5 ¶		skipping to change at page 6, line 7 ¶
	If the location in the "to" member references a member of an existing		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		object in the target document, it is an error condition if a value at
	the specified location already exists (unless "move" and "to" specify		the specified location already exists (unless "move" and "to" specify
	the same object, which has no effect).		the same object, which has no effect).
	If the location in the "to" member references an element of an		If the location in the "to" member references an element of an
	existing array, any elements at or above the specified index are		existing array, any elements at or above the specified index are
	shifted one position to the right. It is an error condition if the		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.		specified index is greater than the number of elements in the array.
			It is an error condition if the "to" member is not present.
	4.5. copy		4.5. copy
	The "copy" operation copies the value at one location to another		The "copy" operation copies the value at one location to another
	location in the target document.		location in the target document.
	The operation object contains a "to" member, a string containing a		The operation object contains a "to" member, a string containing a
	JSON Pointer value that references the location in the target		JSON Pointer value that references the location in the target
	document to add the value to. This location must reference one of:		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		the member to add to an existing object, or an element to add to an
	existing array.		existing array.
	skipping to change at page 6, line 29 ¶		skipping to change at page 6, line 33 ¶
	If the location in the "to" member references a member of an existing		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		object in the target document, it is an error condition if a value at
	the specified location already exists.		the specified location already exists.
	If the location in the "to" member references an element of an		If the location in the "to" member references an element of an
	existing array, any elements at or above the specified index are		existing array, any elements at or above the specified index are
	shifted one position to the right. It is an error condition if the		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.		specified index is greater than the number of elements in the array.
			It is an error condition if the "to" member is not present.
	4.6. test		4.6. test
	The "test" operation tests that a value at the specified location in		The "test" operation tests that a value at the specified location in
	the target document is equal to a specified value. The operation		the target document is equal to a specified value. The operation
	object contains a "value" member that specifies the value to test		object contains a "value" member that specifies the value to test
	for.		for.
	Here, "equal" means that the target and specified values are of the		Here, "equal" means that the target and specified values are of the
	same JSON type, and considered equal by the following rules for that		same JSON type, and considered equal by the following rules for that
	type:		type:
	skipping to change at page 7, line 26 ¶		skipping to change at page 7, line 33 ¶
	Also, note that ordering of the serialisation of object members is		Also, note that ordering of the serialisation of object members is
	not significant.		not significant.
	Example:		Example:
	{ "test": "/a/b/c", "value": "foo" }		{ "test": "/a/b/c", "value": "foo" }
	It is an error condition if the value at the specified location is		It is an error condition if the value at the specified location is
	not equal to the specified value.		not equal to the specified value.
			If the value is not specified, the test is only for presence, not
			value.
			For example:
			{ "test": "/a/b/c" }
			merely tests that the indicated structure is present in the target
			document.
	5. Error Handling		5. Error Handling
	If an error condition occurs, evaluation of the JSON Patch document		If an error condition occurs, evaluation of the JSON Patch document
	SHOULD terminate and application of the entire patch document SHALL		SHOULD terminate and application of the entire patch document SHALL
	NOT be deemed successful. Note that as per [RFC5789], PATCH is		NOT be deemed successful. Note that as per [RFC5789], when used with
	atomic.		the PATCH HTTP method, it is atomic.
			Therefore, the following patch would result in no changes being made
			to the document at all (because the "test" operation results in an
			error).
			[
			{"replace": "/a/b/c", "value": 42},
			{"test": "/a/b/c", "value": "C"}
			]
	6. IANA Considerations		6. IANA Considerations
	The Internet media type for a JSON Patch document is application/		The Internet media type for a JSON Patch document is application/
	json-patch.		json-patch.
	Type name: application		Type name: application
	Subtype name: json-patch		Subtype name: json-patch
	skipping to change at page 8, line 45 ¶		skipping to change at page 9, line 24 ¶
	This specification has the same security considerations as JSON		This specification has the same security considerations as JSON
	[RFC4627] and [JSON-Pointer].		[RFC4627] and [JSON-Pointer].
	8. Acknowledgements		8. Acknowledgements
	The following individuals contributed ideas, feedback and wording to		The following individuals contributed ideas, feedback and wording to
	this specification:		this specification:
	Mike Acar, Mike Amundsen, Paul Davis, Murray S. Kucherawy, Dean		Mike Acar, Mike Amundsen, Paul Davis, Murray S. Kucherawy, Dean
	Landolt, Randall Leeds, Julian Reschke, Eli Stevens.		Landolt, Randall Leeds, Julian Reschke, James Snell, Eli Stevens.
	The structure of a JSON Patch document was influenced by the XML		The structure of a JSON Patch document was influenced by the XML
	Patch document [RFC5261] specification.		Patch document [RFC5261] specification.
	9. References		9. References
	9.1. Normative References		9.1. Normative References
	[JSON-Pointer]		[JSON-Pointer]
	Bryan, P. and K. Zyp, "JSON Pointer",		Bryan, P. and K. Zyp, "JSON Pointer",
	draft-ietf-appsawg-json-pointer-01 (work in progress),		draft-ietf-appsawg-json-pointer-04 (work in progress),
	March 2012.		March 2012.
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	Requirement Levels", BCP 14, RFC 2119, March 1997.		Requirement Levels", BCP 14, RFC 2119, March 1997.
	[RFC4627] Crockford, D., "The application/json Media Type for		[RFC4627] Crockford, D., "The application/json Media Type for
	JavaScript Object Notation (JSON)", RFC 4627, July 2006.		JavaScript Object Notation (JSON)", RFC 4627, July 2006.
	9.2. Informative References		9.2. Informative References
End of changes. 16 change blocks.
	18 lines changed or deleted		45 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/