One document matched: draft-snell-merge-patch-03.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-03"> 
  <front> 
    <title abbrev="application/merge-patch"> 
      The application/json-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>json</keyword> 
    <keyword>patch</keyword> 
    <keyword>merge</keyword>
 
    <abstract> 
      <t>This specification defines the application/json-merge-patch media 
      type and it's intended use with the HTTP PATCH method defined 
      by RFC 5789.</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 a 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 the set of changes being requested.</t>
        </list>
      </t> 
      
      <t>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
      <xref target="RFC4627">JSON format</xref> is one such example.</t>
      
      <t>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:</t> 
      
      <figure><artwork>
  [
   {"add":"title","value":"Goodbye!"},
   {"remove":"link"}
  ]
      </artwork></figure>

      <figure><preamble>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: </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 the 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/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:</t>
      
      <figure><artwork>
  PATCH /patches/1 HTTP/1.1
  Host: example.org
  Content-Type: application/json-merge-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/json-merge-patch" Media Type" anchor="json-merge-patch">
    
      <t>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.</t>
      
      <t>The "application/json-merge-patch" media type MAY contain a "charset" 
      parameter that is used to identify the character set encoding utilized.</t>
      
      <figure><preamble>For example, given the following example JSON document:</preamble>
      <artwork>
  {
    "title": "Goodbye!",
    "author" : {
      "givenName" : "John",
      "familyName" : "Doe"
    },
    "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>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.</t>
             
      <t>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.</t>
    
      <t>A server receiving this patch request MUST apply the following rules
      to determine the specific set of change operations to be performed:
        <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 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 entire 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/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/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.</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/json-merge-patch" Media Type.</t>     
    </section> 
  </middle> 
  <back>
    <references title="Normative References"> 
      &rfc2119;
      &rfc5789;
      &rfc4627;
    </references>
    <references title="Informational References">
      &jsonpatch;
    </references>
  </back>
</rfc>