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.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/