| Network Working Group | J.M. Snell |
| Internet-Draft | June 2012 |
| Intended status: Informational | |
| Expires: December 01, 2012 |
The application/json-merge-patch Media Type
draft-snell-merge-patch-03
This specification defines the application/json-merge-patch media type and it's intended use with the HTTP PATCH method defined by RFC 5789.
This Internet-Draft is submitted to IETF in full conformance with the 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 and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 01, 2012.
Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.
The HTTP PATCH method [RFC5789] provides a mechanism for requesting partial modifications of resources. The payload entity contained by a PATCH request provides a description of the changes that are to be made to a target resource. The general term used to describe such payloads is a "Patch Document".
A partial modification request using PATCH can generally take one of two forms. The Patch Document can either
Either approach is valid. However, it is important to note that when using PATCH with the second approach -- generally termed a "Merge Patch" within this specification -- it is often difficult for a server to determine the user agent's exact intent when using generic media types that do not have clearly defined PATCH semantics. The JSON format [RFC4627] is one such example.
To best illustrate the problem -- albeit with an example that is somewhat extreme -- consider an example where a user agent wishes to modify the following JSON Patch Document currently existing on a server:
[
{"add":"title","value":"Goodbye!"},
{"remove":"link"}
]
Supposing the user agent wishes to remove the "remove" statement from the document and change the "value" of the "title" from "Goodbye" to "Hello World", if it sends the following request to the server intending to perform a Merge Patch style modification:
PATCH /patches/1 HTTP/1.1
Host: example.org
Content-Type: application/json-patch
[{"add":"title","value":"Hello world"}]
The server has no choice but to interpret the request as a normal JSON Patch operation, resulting in an unintended modification of the target resource.
What is needed in this case is a mechanism that will allow the user agent sending the PATCH request to explicitly signal that it is requesting a Merge Patch style modification of the resource.
Using the "application/json-merge-patch" Media Type defined herein, the user agent's original intent can be clearly and unambiguously communicated to the server within the request:
PATCH /patches/1 HTTP/1.1
Host: example.org
Content-Type: application/json-merge-patch; charset="UTF-8"
[{"add":"title","value":"Hello world"}]
In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC2119].
The "application/json-merge-patch" Media Type is used to identify JSON documents that describe, by example, a set of changes that are to be made to a target resource. When used within an HTTP PATCH request, it is the responsibility of the server receiving and processing the request to inspect the payload entity and determine the specific set of operations that are to be performed to modify the target resource. The actual set of modifications to be made will be specific to the semantics and requirements of the target resource.
The "application/json-merge-patch" media type MAY contain a "charset" parameter that is used to identify the character set encoding utilized.
For example, given the following example JSON document:
{
"title": "Goodbye!",
"author" : {
"givenName" : "John",
"familyName" : "Doe"
},
"tags":["example","sample"]
}
If the intent is to change the value of the "title" property to from "Goodbye!" to the value "Hello!", add a new "phoneNumber" property, remove the "familyName" property from the "author" object, and remove the word sample from the "tags" Array, the user-agent would send the following request:
PATCH /my/resource HTTP/1.1
Host: example.org
Content-Type: application/json-merge-patch; charset="UTF-8"
{
"title": "Hello!",
"phoneNumber": "+01-123-456-7890",
"author": {
"familyName": null
}
"tags": ["example"]
}
Upon receiving the request, the server is responsible for inspecting the payload and determining, based on it's own understanding of the target resource media type and the underlying data model the target resource represents, what specific operations will be applied to modify the resource.
Note that while the payload of "application/json-merge-patch" resources MUST be a JSON Object or Array, the target resource to which a PATCH request using "application/json-merge-patch" is sent can be of any arbitrary media type.
A server receiving this patch request MUST apply the following rules to determine the specific set of change operations to be performed:
Applying these rules to the previous example, the set of specific change operations the server would derive from the request would be:
Note that once the set of intended modifications is derived from the request, the server is free to determine the appropriateness of the modification based on it's own understanding of the target resource. For instance, in the previous example, it is possible that the "familyName" property could be required within the target resource and cannot be removed. Note that in such cases, per [RFC5789], Section 2, the server is REQUIRED to reject the entire PATCH request using an HTTP error response code appropriate to the error condition.
If the request attempts to remove a property from the target resource that does not currently exist, the server SHOULD NOT consider the request to be in error. The requested removal operation SHOULD simply be ignored by the server as the final modified state of the target resource will still accurately reflect the user-agent's original intention.
This specification registers the following additional MIME Media Types:
The "application/json-merge-patch" Media Type allows user agents to indicate their intention that the server determine the specific set of change operations to be applied to a target resource. As such, it is the servers responsibility to determine the appropriateness of any given change as well as the user agent's authorization to request such changes. How such determinations are made is considered out of the scope of this specification.
All of the the security considerations discussed in Section 5 [RFC5789] apply to all uses of the HTTP PATCH method with the "application/json-merge-patch" Media Type.
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |
| [RFC5789] | Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, March 2010. |
| [RFC4627] | Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006. |
| [I-D.ietf-appsawg-json-patch] | Bryan, P, "JSON Patch", Internet-Draft draft-ietf-appsawg-json-patch-01, March 2012. |