One document matched: draft-snell-merge-patch-02.xml

<?xml version="1.0"?> 
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
  <!ENTITY rfc5789 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5789.xml'>  
  <!ENTITY rfc2119 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
  <!ENTITY rfc4627 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml'>
  <!ENTITY jsonpatch PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-appsawg-json-patch-01.xml'>
]>
<?rfc toc="yes"?> 
<?rfc strict="yes"?> 
<?rfc symrefs="yes" ?> 
<?rfc sortrefs="yes"?> 
<?rfc compact="yes"?> 
<rfc category="info" ipr="trust200811" docName="draft-snell-merge-patch-02"> 
  <front> 
    <title abbrev="application/merge-patch"> 
      The application/merge-patch Media Type
    </title> 
 
    <author initials="J.M." surname="Snell" fullname="James M Snell"> 
      <address> 
        <email>jasnell@gmail.com</email> 
      </address> 
    </author> 
    
    <date month="June" year="2012" /> 
 
    <area>Applications</area> 
    <!-- workgroup>Individual Submission</workgroup--> 
    <keyword>I-D</keyword> 
    <keyword>http</keyword> 
    <keyword>patch</keyword> 
    <keyword>merge</keyword>
 
    <abstract> 
      <t>This specification defines the application/merge-patch media 
      type and it's intended use with the HTTP PATCH method defined 
      by RFC 5789; as well as the "application/json+merge-patch" variation
      that defines the "Merge Patch" semantics for JSON documents.</t> 
    </abstract> 
 
  </front> 
  
  <middle> 
    <section anchor="intro" title="Introduction"> 
 
      <t>The HTTP PATCH method <xref target="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 the target resource. The 
      general term used to describe such payloads is a "Patch Document".</t>
      
      <t>A partial modification request using PATCH can generally take one of
      two forms. The Patch Document can either
        <list style="symbols">
          <t>Provide an explicit description of the changes being requested --
          as is done, for instance, with the JSON Patch format described 
          in <xref target="I-D.ietf-appsawg-json-patch"/> -- or,</t>
          <t>Provide a modified version of the original resource and allow
          the Server to determine to specific set of changes being requested.</t>
        </list>
      </t> 
      
      <t>Either approach is equally valid. However, it is important to note that 
      when using PATCH with the second approach -- generally called a "Merge Patch" --
      it is often difficult for a server to determine the clients exact intent
      when generic media types that do not have clearly defined PATCH semantics 
      defined are used.</t>
      
      <t>To best illustrate the problem -- albeit with an example that is 
      somewhat extreme -- consider an example where we have the following JSON Patch 
      Document currently existing on a server that we wish to modify:</t> 
      
      <figure><artwork>
  [
   {"add":"title","value":"Goodbye!"},
   {"remove":"link"}
  ]
      </artwork></figure>
      
      <figure><preamble>If we send the following request to the server intending
      to perform a Merge Patch style modification: </preamble>
      <artwork>
  PATCH /patches/1 HTTP/1.1
  Host: example.org
  Content-Type: application/json-patch
  
  [{"add":"title","value":"Hello world"}]
      </artwork></figure>
      
      <t>The server has no choice but to interpret this request as a normal
      JSON Patch operation, resulting in an unintended modification of the 
      target resource.</t>
      
      <t>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.</t>
      
      <t>Using the "application/merge-patch" Media Type defined herein, the 
      user agents original intent can be clearly and unambiguously communicated
      to the server within the request:</t>
      
      <figure><artwork>
  PATCH /patches/1 HTTP/1.1
  Host: example.org
  Content-Type: application/merge-patch; 
    type="application/json+patch"; charset="UTF-8"
  
  [{"add":"title","value":"Hello world"}]
      </artwork></figure>
      
      <t>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 <xref target="RFC2119" />.</t> 
 
    </section> 
    
    <section title="The "application/merge-patch" Media Type">
    
      <t>The "application/merge-patch" Media Type is used to identify 
      document resources 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 media type of the target resource.</t>
      
      <figure><preamble>For example, given the following example JSON document:</preamble>
      <artwork>
  {
    "title": "Goodbye!",
    "author" : {
      "givenName" : "James",
      "familyName" : "Snell"
    },
    "tags":["example","sample"]
  }
      </artwork></figure>
      
      <t>If my intent is to change only the value of the "title" property 
      from it's current value "Goodbye!" to the new value "Hello!", I would 
      send the following request:</t>
      
      <figure><artwork>
  PATCH /my/resource HTTP/1.1
  Host: example.org
  Content-Type: application/merge-patch; 
    type="application/json"; charset="UTF-8""
  
  {
    "title": "Hello!"
  }
      </artwork></figure>
   
      <t>Upon receiving the request, the server is responsible for inspecting
      the payload and will determine, 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.</t>
      
      <t>The "application/merge-patch" media type intentionally makes the 
      receiving party responsible for determining how the target resource 
      is to be modified.</t>
      
      <section title="The "type" Parameter">
        <t>By itself, the "application/merge-patch" media type does not 
        define a specific serialization format and MAY contain data of 
        any type.</t>
        
        <t>Unless using a <xref target="type-specific-variation">type-specific 
        variation</xref> of the "application/merge-patch" media type, such
        as <xref target="json-merge-patch">"application/json+merge-patch"</xref>,
        the "application/merge-patch" MUST specify a type parameter whose value
        is the actual MIME Media Type of the payload.</t>
      
        <figure><preamble>For example, if using the "application/merge-patch"
        media type to request modifications in an XML document, the "type" 
        parameter would specify the appropriate XML media type:</preamble>
        <artwork><![CDATA[
  PATCH /my/resource HTTP/1.1
  Host: example.org
  Content-Type: application/merge-patch; 
    type="application/xml"; charset="UTF-8"
  
  <abc>
    <xyz>foo</xyz>
  </abc>
        ]]></artwork></figure>
      </section>
      
      <section title="The "charset" Parameter">
      
        <t>When the "application/merge-patch" resource contains character-based
        data (e.g. plain text, XML, JSON, and so forth), the "charset" parameter
        SHOULD be used to identify the character set encoding utilized.</t>
      
      </section>
      
      <section title="Type-Specific Variations" anchor="type-specific-variation">
      
        <t>This document recommends the use of a naming convention (a suffix 
        of "+merge-patch") for identifying Media Type specific variations of 
        "application/merge-patch".</t>
        
        <t>Media Type specific variations of "application/merge-patch" 
        define the specific details of how a server SHOULD derive the set of 
        actual change operations being requested in a PATCH operation relative
        to one or more specific media types. The variation also defines the 
        specific payload type required for the request.</t>
        
        <t>When a Media Type specific variation is used, such as "application/json+merge-patch",
        the "type" parameter MAY be specified to provide additional specific 
        type information.</t>
        
        <figure><preamble>In the following example, the request clearly indicates
        that the "application/json+merge-patch" Type Specific Variation is 
        utilized with the "type" attribute providing additional contextual 
        information about what specific variation of the JSON Document format
        is contained in the request.</preamble><artwork>
  PATCH /my/resource HTTP/1.1
  Host: example.org
  Content-Type: application/json+merge-patch; 
    type="application/stream+json"; charset="UTF-8"
    
  {
    "verb": "POST"
  }
        </artwork></figure>
      
      </section>
    
    </section>
    
    <section title="The "application/json+merge-patch" Type Specific Variation" anchor="json-merge-patch">
    
      <t>The "application/json+merge-patch" Media Type is a Type Specific 
      Variation of the "application/merge-patch" Media Type that uses 
      a JSON data structure to describe the changes to be made to a target 
      resource.</t>
      
      <figure><preamble>For example, given the following example JSON document:</preamble>
      <artwork>
  {
    "title": "Goodbye!",
    "author" : {
      "givenName" : "James",
      "familyName" : "Snell"
    },
    "tags":["example","sample"]
  }
      </artwork></figure>
      
      <t>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:</t>
      
      <figure><artwork>
  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"]
  }
      </artwork></figure>
      
      <t>Note that while the payload of "application/json+merge-patch" 
      resources MUST be any valid subtype of the "application/json" media
      type, the target resource to which a PATCH request using "application/json+merge-patch"
      is sent can be of any arbitrary media type. It is the server's responsibility
      to determine how to apply the specific semantics of the Merge Patch
      operation to the target resource.</t>
    
      <t>A server receiving this patch request MUST determine the specific
      set of change operations to be performed by analyzing the JSON data
      contained in the payload of the request relative to the target resource
      and applying the following rules:
        <list style="numbers">
        <t>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 JSON data.</t>
        
        <t>If the root of the JSON data provided in the payload is a 
        JSON Object, for each distinct property specified in that object:
          <list style="symbols">
            <t>If the property is currently not specified for the target resource,
            the property and the given value is to be added to the target.</t>
            <t>If the value is explicitly set to null and that property is currently 
            specified for the target resource, the existing value is removed.</t>
            <t>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.</t>
            <t>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.</t>
            <t>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.</t>
          </list>
        </t>
        </list>
      </t>
      
      <t>Applying these rules to the previous example, the set of specific 
      change operations the server would derive from the request would be:
        <list style="symbols">
          <t>Change the existing value of the "title" property from "Goodbye!"
          to "Hello!",</t>
          <t>Add the "phoneNumber" property with a value of "+01-123-456-7890",</t>
          <t>Remove the "familyName" property from the current object value 
          associated with the "author" property, and </t>
          <t>Change the existing value of the "tags" property from 
          ["example","sample"] to ["example"].</t>
        </list>
      </t>
      
      <t>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 <xref target="RFC5789"/>, Section 2, 
      the server is REQUIRED to reject the PATCH request using an HTTP error 
      response code appropriate to the error condition.</t>
      
      <t>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.</t>
    
    </section>
             
    <section title="IANA Considerations"> 
      <t>This specification registers the following additional 
      MIME Media Types:</t>
      
      <section title="application/merge-patch">
        <t><list>
        <t>Type name: application</t>
        <t>Subtype name: merge-patch</t>
        <t>Required parameters: "type" : A MIME Media Type</t>
        <t>Optional parameters: "charset" : Specifies the character set encoding 
        type when the "application/merge-patch" resource contains character-based
        content.</t>
        <t>Encoding considerations: The specific encoding considerations will 
        vary dependent on the specific MIME Media Type specified by the "type"
        parameter.</t>
        <t>Security considerations: As defined in this specification.</t>
        <t>Interoperability considerations: There are no known interoperability issues.</t>
        <t>Published specification: This specification.</t>
        <t>Applications that use this media type: This media type is intended 
        primarily for use with the HTTP PATCH method.</t>
        <t>Additional information:
        <list>
        <t>Magic number(s): N/A</t>
        <t>File extension(s): N/A</t>
        <t>Macintosh file type code(s): "BINARY"</t>
        </list></t>
        <t>Person & email address to contact for further information: James M Snell <jasnell@gmail.com></t>
        <t>Intended usage: COMMON</t>
        <t>Restrictions on usage: None.</t>
        <t>Author: James M Snell <jasnell@gmail.com></t>
        <t>Change controller: IETF</t>
        </list></t>
      </section>

      <section title="application/json+merge-patch">
        <t><list>
        <t>Type name: application</t>
        <t>Subtype name: json+merge-patch</t>
        <t>Required parameters: None</t>
        <t>Optional parameters: "charset" : Specifies the character set encoding.
        If not specified, a default of "UTF-8" is assumed.</t>
        <t>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 <xref target="RFC4627">Section 6</xref>.</t>
        <t>Security considerations: As defined in this specification.</t>
        <t>Interoperability considerations: There are no known interoperability issues.</t>
        <t>Published specification: This specification.</t>
        <t>Applications that use this media type: This media type is intended 
        primarily for use with the HTTP PATCH method.</t>
        <t>Additional information:
        <list>
        <t>Magic number(s): N/A</t>
        <t>File extension(s): N/A</t>
        <t>Macintosh file type code(s): "TEXT"</t>
        </list></t>
        <t>Person & email address to contact for further information: James M Snell <jasnell@gmail.com></t>
        <t>Intended usage: COMMON</t>
        <t>Restrictions on usage: None.</t>
        <t>Author: James M Snell <jasnell@gmail.com></t>
        <t>Change controller: IETF</t>
        </list></t>
      </section>
      
    </section> 
      
    <section title="Security Considerations"> 
      <t>The "application/merge-patch" Media Type and all Type-Specific
      Variations are intended for use as a mechanism to allow user-agents
      requesting partial modification of a target resource to indicate
      an intention for the server to determine the specific set of change
      operations that are to be applied to the target resource. As such, 
      it is the servers responsibility to determine the appropriateness 
      of any given change as well as the user-agents authorization to 
      request such changes.</t>
      
      <t>All of the the security considerations discussed in 
      <xref target="RFC5789">Section 5</xref> apply to all uses of the 
      HTTP PATCH method with the "application/merge-patch" Media Type 
      (and all Type-Specific Variations).</t>     
    </section> 
  </middle> 
  <back>
    <references title="Normative References"> 
      &rfc2119;
      &rfc5789;
      &rfc4627;
    </references>
    <references title="Informational References">
      &jsonpatch;
    </references>
  </back>
</rfc>