One document matched: draft-snell-merge-patch-04.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-05.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-04"> 
  <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="October" 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 subset 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, 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
      <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>
  [
   {"op": "add", "path": "/title", "value":"Goodbye!"},
   {"op": "remove", "path": "/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
  
  [{"op":"add", "path": "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"
  
  [{"op":"add", "path": "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"],
    "content": "This will be unchanged"
  }
      </artwork></figure>
      
      <t>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 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>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 an 
        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 an 
        Object, for each distinct member specified in that object:
          <list style="symbols">
            <t>If the member is currently undefined within the target resource,
            the member and the given value is to be added to the target.</t>
            <t>If the value is explicitly set to null and that member is currently 
            defined within the target resource, the existing member is removed.</t>
            <t>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.</t>
            <t>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.</t>
            <t>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.</t>
            <t>Any member currently defined within the target resource that 
            does not explicitly appear within the patch is to remain untouched
            and unmodified.</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" member from "Goodbye!"
          to "Hello!",</t>
          <t>Add the "phoneNumber" member with a value of "+01-123-456-7890",</t>
          <t>Remove the "familyName" member from the current object value 
          associated with the "author" member, and </t>
          <t>Change the existing value of the "tags" member from 
          ["example","sample"] to ["example"].</t>
        </list>
      </t>
      
      <figure><preamble>The resulting JSON document would be similar to (note
      that the specific ordering of members within JSON documents is insigificant):</preamble>
          <artwork>
      {
        "title": "Hello!",
        "author" : {
          "givenName" : "John"
        },
        "tags":["example"],
        "content": "This will be unchanged",
        "phoneNumber": "+01-123-456-7890"
      }
      </artwork></figure>
      
      <t>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 <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 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.</t>
    
    </section>
             
    <section title="IANA Considerations"> 
      <t>This specification registers the following additional 
      MIME Media Types:</t>

      <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>Published specification: This specification.</t>
      <t>Applications that use this media type: None currently known.</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: IESG</t>
      </list></t>
      
    </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 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.</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>