< draft-pbryan-json-patch-03.txt		draft-pbryan-json-patch-04.txt >
	Internet Engineering Task Force P. Bryan, Ed.		Internet Engineering Task Force P. Bryan, Ed.
	Internet-Draft ForgeRock US, Inc.		Internet-Draft ForgeRock US, Inc.
	Intended status: Informational December 4, 2011		Intended status: Informational December 4, 2011
	Expires: June 6, 2012		Expires: June 6, 2012
	JSON Patch		JSON Patch
	draft-pbryan-json-patch-03		draft-pbryan-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 partial modifications		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
	provisions of BCP 78 and BCP 79.		provisions of BCP 78 and BCP 79.
	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-
	skipping to change at page 2, line 14 ¶		skipping to change at page 2, line 14 ¶
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
	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 . . . . . . . . . . . . . . . . . . . . . . . . . 4		4.3. replace . . . . . . . . . . . . . . . . . . . . . . . . . 4
	4.4. move . . . . . . . . . . . . . . . . . . . . . . . . . . . 4		4.4. move . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
	4.5. test . . . . . . . . . . . . . . . . . . . . . . . . . . . 5		4.5. test . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
	5. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 5		5. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 6
	6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5		6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
	7. Security Considerations . . . . . . . . . . . . . . . . . . . 6		7. Security Considerations . . . . . . . . . . . . . . . . . . . 7
	8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 6		8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7
	9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6		9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7
	9.1. Normative References . . . . . . . . . . . . . . . . . . . 6		9.1. Normative References . . . . . . . . . . . . . . . . . . . 7
	9.2. Informative References . . . . . . . . . . . . . . . . . . 7		9.2. Informative References . . . . . . . . . . . . . . . . . . 8
	Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 7		Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 8
	A.1. Adding an Object Member . . . . . . . . . . . . . . . . . 7		A.1. Adding an Object Member . . . . . . . . . . . . . . . . . 8
	A.2. Adding an Array Element . . . . . . . . . . . . . . . . . 7		A.2. Adding an Array Element . . . . . . . . . . . . . . . . . 8
	A.3. Removing an Object Member . . . . . . . . . . . . . . . . 8		A.3. Removing an Object Member . . . . . . . . . . . . . . . . 9
	A.4. Removing an Array Element . . . . . . . . . . . . . . . . 8		A.4. Removing an Array Element . . . . . . . . . . . . . . . . 9
	A.5. Replacing a Value . . . . . . . . . . . . . . . . . . . . 9		A.5. Replacing a Value . . . . . . . . . . . . . . . . . . . . 10
	A.6. Moving a Value . . . . . . . . . . . . . . . . . . . . . . 9		A.6. Moving a Value . . . . . . . . . . . . . . . . . . . . . . 10
	A.7. Moving an Array Element . . . . . . . . . . . . . . . . . 10		A.7. Moving an Array Element . . . . . . . . . . . . . . . . . 11
	A.8. Testing a Value: Success . . . . . . . . . . . . . . . . . 10		A.8. Testing a Value: Success . . . . . . . . . . . . . . . . . 11
	A.9. Testing a Value: Error . . . . . . . . . . . . . . . . . . 11		A.9. Testing a Value: Error . . . . . . . . . . . . . . . . . . 12
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11		Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12
	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 HTTP [RFC2616] with a method to perform partial modifications		extends HTTP [RFC2616] with a method to perform partial modifications
	to resources.		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
	structure for expressing a sequence of partial modifications to a		structure for expressing a sequence of operations to apply to a
	JSON document, suitable for use with the HTTP PATCH method.		target JSON document, suitable for use with the HTTP PATCH method.
	2. Conventions		2. Conventions
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",		The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this		"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
	document are to be interpreted as described in RFC 2119 [RFC2119].		document are to be interpreted as described in RFC 2119 [RFC2119].
	3. Document Structure		3. Document Structure
	A JSON Patch document contains a JSON array of objects. Each object		A JSON Patch document contains a JSON array of objects. Each object
	contains a single operation to apply to the target JSON document.		contains a single operation to apply to the target JSON document.
	A sample JSON Patch document:		An example JSON Patch document:
	[		[
	{ "test": "/a/b/c", value: "foo" },		{ "test": "/a/b/c", value: "foo" },
	{ "remove": "/a/b/c" },		{ "remove": "/a/b/c" },
	{ "add": "/a/b/c", "value": [ "foo", "bar" ] },		{ "add": "/a/b/c", "value": [ "foo", "bar" ] },
	{ "replace": "/a/b/c", "value": 42 },		{ "replace": "/a/b/c", "value": 42 },
	{ "move": "/a/b/c", to: "/a/b/d" }		{ "move": "/a/b/c", to: "/a/b/d" }
	]		]
	Evaluation of a JSON Patch document begins with a target JSON		Evaluation of a JSON Patch document begins with a target JSON
	document to modify. Operations are applied sequentially in the order		document. Operations are applied sequentially in the order they
	they appear in the array. Each operation in the sequence is applied		appear in the array. Each operation in the sequence is applied to
	to the target document. The resulting modified document becomes the		the target document; the resulting document becomes the target of the
	target for the next operation. The process repeats until all		next operation. Evaluation continues until all operations are
	operations are successfully applied.		successfully applied or an error condition is encountered.
	4. Operations		4. Operations
	The operation to perform is expressed in the name of a member in the		The operation to apply is expressed in a member of the operation
	operation object; it's value is a string containing a [JSON Pointer],		object. The name of the operation member is one of: "add", "remove",
	which references the value for which to apply the operation. It is		"replace", "move" or "test". The member value is a string containing
	an error condition if an operation object contains more than one		a [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.		operation member.
	4.1. add		4.1. add
	The "add" operation adds a new value into the target document. The		The "add" operation adds a new value to the target document at the
	value to be added is specified in the operation object's "value"		specified location. The location must reference one of: the root of
	member.		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.
	If adding to an object, it is an error condition if the member to be		Example:
	added in the object already exists.
	If adding to an array, all elements at or above the specified index		{ "add": "/a/b/c", "value": [ "foo", "bar" ] }
	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		If the location references the root of the target document or a
	existing array.		member of an existing object, it is an error condition if a value at
			the specified location already exists.
			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.
	4.2. remove		4.2. remove
	The "remove" operation removes a value from the target document.		The "remove" operation removes the value in the target document at
			the specified location.
	If removing an element from an array, all elements above the		Example:
			{ "remove": "/a/b/c" }
			If removing an element from an array, any elements above the
	specified index are shifted one position to the left.		specified index are shifted one position to the left.
	It is an error condition if the value to be removed does not exist.		It is an error condition if a value at the specified location does
			not exist.
	4.3. replace		4.3. replace
	The "replace" operation replaces an existing value in the target		The "replace" operation replaces the value in the target document at
	document with a new value. The value to replace the existing value		the specified location with a new value. The operation object
	with is specified in the operation object's "value" member.		contains a "value" member, which specifies the replacement value.
	This operation is semantically equivalent to expressing a "remove"		Example:
	operation for a value, followed immediately by an "add" operation at
	the same location of the removed value.
	It is an error condition if the value to be replaced does not exist.		{ "replace": "/a/b/c", "value": 42 }
			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.
			It is an error condition if a value at the specified location does
			not exist.
	4.4. move		4.4. move
	The "move" operation moves a value from one location to another		The "move" operation removes the value at one location and adds it to
	within the target document. The location to move the value to is		another location in the target document.
	specified in the operation object's "to" member, a string containing
	a JSON Pointer.
	This operation is semantically equivalent to expressing a "remove"		The operation object contains a "to" member, a string containing a
	operation, followed immediately by an "add" operation with the		JSON Pointer which references the location in the target document to
	removed value.		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.
	It is an error condition if the value to be moved does not exist, or		Example:
	if the location to move the value to already has a value.
			{ "move": "/a/b/c", to: "/a/b/d" }
			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.
			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.
			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.
	4.5. test		4.5. test
	The "test" operation tests that a value in the target document is		The "test" operation tests that a value in the target document at the
	equal to the specified value. The value to test for is specified in		specified location is equal to a specified value. The operation
	the operation object's "value" member.		object contains a "value" member, which specifies the value to test
			for.
			Example:
			{ "test": "/a/b/c", value: "foo" }
	It is an error condition if the value in the target document is not		It is an error condition if the value in the target document is not
	equal to the specified value.		equal to the specified value.
	5. Error Handling		5. Error Handling
	In the event of an error condition, evaluation of the JSON Patch		If an error condition occurs, evaluation of the JSON Patch document
	document SHOULD terminate and application of the entire patch		SHOULD terminate and application of the entire patch document SHALL
	document MUST NOT be deemed successful.		NOT be deemed successful.
	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
	Required parameters: none		Required parameters: none
	Optional parameters: none		Optional parameters: none
	Encoding considerations:		Encoding considerations:
	Per JSON [RFC4627]: 8bit if UTF-8; binary if UTF-16 or UTF-32.		Per JSON [RFC4627]: 8bit if UTF-8; binary if UTF-16 or UTF-32.
	Security considerations:		Security considerations:
	See Security Considerations in section 8.		See Security Considerations in section 7.
	Interoperability considerations: N/A		Interoperability considerations: N/A
	Published specification:		Published specification:
	draft-pbryan-json-patch-03		draft-pbryan-json-patch-04
	Applications that use this media type:		Applications that use this media type:
	Applications that manipulate JSON documents.		Applications that manipulate JSON documents.
	Additional information:		Additional information:
	Magic number(s): N/A		Magic number(s): N/A
	File extension(s): .json-patch		File extension(s): .json-patch
	Macintosh file type code(s): TEXT		Macintosh file type code(s): TEXT
	Person & email address to contact for further information:		Person & email address to contact for further information:
	Paul C. Bryan <paul.bryan@forgerock.com>		Paul C. Bryan <paul.bryan@forgerock.com>
	Intended usage: COMMON		Intended usage: COMMON
	Restrictions on usage: none		Restrictions on usage: none
End of changes. 25 change blocks.
	70 lines changed or deleted		108 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/