One document matched: draft-snell-merge-patch-03.txt
Differences from draft-snell-merge-patch-02.txt
Network Working Group J. Snell
Internet-Draft June 19, 2012
Intended status: Informational
Expires: December 21, 2012
The application/json-merge-patch Media Type
draft-snell-merge-patch-03
Abstract
This specification defines the application/json-merge-patch media
type and it's intended use with the HTTP PATCH method defined by RFC
5789.
Status of this Memo
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 21, 2012.
Copyright Notice
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. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Snell Expires December 21, 2012 [Page 1]
Internet-Draft application/merge-patch June 2012
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. The "application/json-merge-patch" Media Type . . . . . . . . . 4
3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6
3.1. application/json-merge-patch . . . . . . . . . . . . . . . 6
4. Security Considerations . . . . . . . . . . . . . . . . . . . . 7
5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.1. Normative References . . . . . . . . . . . . . . . . . . . 7
5.2. Informational References . . . . . . . . . . . . . . . . . 8
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8
Snell Expires December 21, 2012 [Page 2]
Internet-Draft application/merge-patch June 2012
1. Introduction
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
o Provide an explicit description of the changes being requested --
as is done, for instance, with the JSON Patch format described in
[I-D.ietf-appsawg-json-patch] -- or,
o Provide a modified version of the original resource and allow the
Server to determine the set of changes being requested.
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.
Snell Expires December 21, 2012 [Page 3]
Internet-Draft application/merge-patch June 2012
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].
2. The "application/json-merge-patch" Media Type
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
Snell Expires December 21, 2012 [Page 4]
Internet-Draft application/merge-patch June 2012
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:
1. If the root of the JSON data provided in the payload is a JSON
Array, the target resource is to be replaced, in whole, by the
provided data.
2. If the root of the JSON data provided in the payload is a JSON
Object, for each distinct property specified in that object:
* If the property is currently not specified for the target
resource, the property and the given value is to be added to
the target.
* If the value is explicitly set to null and that property is
currently specified for the target resource, the existing
value is removed.
* If the value is either a non-null JSON primitive or an Array
and that property is currently specified for the target
resource, the existing value is to be replaced with that
provided.
* If the value is a JSON object and that property is currently
specified for the target resource and the existing value is a
JSON primitive or Array, the existing value is to be replaced
in whole by the object provided.
Snell Expires December 21, 2012 [Page 5]
Internet-Draft application/merge-patch June 2012
* If the value is a JSON object and that property is currently
specified for the target resource and the existing value is
also a JSON object, then recursively apply Rule #2 to each
object.
Applying these rules to the previous example, the set of specific
change operations the server would derive from the request would be:
o Change the existing value of the "title" property from "Goodbye!"
to "Hello!",
o Add the "phoneNumber" property with a value of "+01-123-456-7890",
o Remove the "familyName" property from the current object value
associated with the "author" property, and
o Change the existing value of the "tags" property from
["example","sample"] to ["example"].
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.
3. IANA Considerations
This specification registers the following additional MIME Media
Types:
3.1. application/json-merge-patch
Type name: application
Subtype name: json-merge-patch
Required parameters: None
Optional parameters: "charset" : Specifies the character set
encoding. If not specified, a default of "UTF-8" is assumed.
Encoding considerations: Resources that use the "application/
json-merge-patch" media type are required to conform to the
"application/json" Media Type and are therefore subject to the
same encoding considerations specified in Section 6 [RFC4627].
Snell Expires December 21, 2012 [Page 6]
Internet-Draft application/merge-patch June 2012
Security considerations: As defined in this specification.
Interoperability considerations: There are no known
interoperability issues.
Published specification: This specification.
Applications that use this media type: This media type is intended
primarily for use with the HTTP PATCH method.
Additional information:
Magic number(s): N/A
File extension(s): N/A
Macintosh file type code(s): "TEXT"
Person & email address to contact for further information: James M
Snell <jasnell@gmail.com>
Intended usage: COMMON
Restrictions on usage: None.
Author: James M Snell <jasnell@gmail.com>
Change controller: IETF
4. Security Considerations
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.
5. References
5.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
RFC 5789, March 2010.
Snell Expires December 21, 2012 [Page 7]
Internet-Draft application/merge-patch June 2012
5.2. Informational References
[I-D.ietf-appsawg-json-patch]
Bryan, P., "JSON Patch", draft-ietf-appsawg-json-patch-01
(work in progress), March 2012.
Author's Address
James M Snell
Email: jasnell@gmail.com
Snell Expires December 21, 2012 [Page 8]
| PAFTECH AB 2003-2026 | 2026-04-24 04:10:54 |