[Docs] [txt|pdf|xml|html] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04 05 06 07 08 draft-ietf-appsawg-json-merge-patch

Network Working Group                                           J. Snell
Internet-Draft                                           October 4, 2012
Intended status: Informational
Expires: April 7, 2013


              The application/json-merge-patch Media Type
                       draft-snell-merge-patch-04

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 April 7, 2013.

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 April 7, 2013                 [Page 1]


Internet-Draft           application/merge-patch            October 2012


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 3
   2.  The "application/json-merge-patch" Media Type . . . . . . . . . 4
   3.  IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6
   4.  Security Considerations . . . . . . . . . . . . . . . . . . . . 7
   5.  References  . . . . . . . . . . . . . . . . . . . . . . . . . . 7
     5.1.  Normative References  . . . . . . . . . . . . . . . . . . . 7
     5.2.  Informational References  . . . . . . . . . . . . . . . . . 8
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . . . 8









































Snell                     Expires April 7, 2013                 [Page 2]


Internet-Draft           application/merge-patch            October 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 subset of the original resource and allow the
      Server to determine the set of changes being requested.

   Either approach is valid.  However, when using the latter approach --
   generally termed a "Merge Patch" within this specification -- it is
   often difficult for a server to determine the client'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:

     [
      {"op": "add", "path": "/title", "value":"Goodbye!"},
      {"op": "remove", "path": "/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

     [{"op":"add", "path": "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



Snell                     Expires April 7, 2013                 [Page 3]


Internet-Draft           application/merge-patch            October 2012


   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"

     [{"op":"add", "path": "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"],
       "content": "This will be unchanged"
     }

   If the intent is to change the value of the "title" member to from
   "Goodbye!" to the value "Hello!", add a new "phoneNumber" member,
   remove the "familyName" member from the "author" object, and remove



Snell                     Expires April 7, 2013                 [Page 4]


Internet-Draft           application/merge-patch            October 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.

   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 an 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 an
       Object, for each distinct member specified in that object:
       *  If the member is currently undefined within the target
          resource, the member and the given value is to be added to the
          target.
       *  If the value is explicitly set to null and that member is
          currently defined within the target resource, the existing
          member is removed.
       *  If the value is either a non-null JSON primitive or an Array
          and that member is currently defined within the target
          resource, the existing value for that member is to be replaced
          with that provided.
       *  If the value is a JSON object and that member is currently
          defined 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.
       *  If the value is a JSON object and that member is currently
          defined within the target resource and the existing value is
          also a JSON object, then recursively apply Rule #2 to each
          object.




Snell                     Expires April 7, 2013                 [Page 5]


Internet-Draft           application/merge-patch            October 2012


       *  Any member currently defined within the target resource that
          does not explicitly appear within the patch is to remain
          untouched and unmodified.

   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" member from "Goodbye!" to
      "Hello!",
   o  Add the "phoneNumber" member with a value of "+01-123-456-7890",
   o  Remove the "familyName" member from the current object value
      associated with the "author" member, and
   o  Change the existing value of the "tags" member from
      ["example","sample"] to ["example"].

   The resulting JSON document would be similar to (note that the
   specific ordering of members within JSON documents is insigificant):

         {
           "title": "Hello!",
           "author" : {
             "givenName" : "John"
           },
           "tags":["example"],
           "content": "This will be unchanged",
           "phoneNumber": "+01-123-456-7890"
         }

   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" member might 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 member from the target resource
   that does not currently exist, the server SHOULD NOT consider the
   request to be in error.  The requested removal operation is 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:



Snell                     Expires April 7, 2013                 [Page 6]


Internet-Draft           application/merge-patch            October 2012


      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].
      Security considerations: As defined in this specification
      Published specification: This specification.
      Applications that use this media type: None currently known.
      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: IESG


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 server's 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.



Snell                     Expires April 7, 2013                 [Page 7]


Internet-Draft           application/merge-patch            October 2012


   [RFC5789]  Dusseault, L. and J. Snell, "PATCH Method for HTTP",
              RFC 5789, March 2010.

5.2.  Informational References

   [I-D.ietf-appsawg-json-patch]
              Bryan, P. and M. Nottingham, "JSON Patch",
              draft-ietf-appsawg-json-patch-05 (work in progress),
              September 2012.


Author's Address

   James M Snell

   Email: jasnell@gmail.com



































Snell                     Expires April 7, 2013                 [Page 8]


Html markup produced by rfcmarkup 1.123, available from https://tools.ietf.org/tools/rfcmarkup/