Applications Area Working Group                               C. Bormann
Internet-Draft                                   Universitaet Bremen TZI
Intended status: Standards Track                         P. van der Stok
Expires: September 22, 2016                                   Consultant
                                                          March 21, 2016


                            CBOR Merge Patch
               draft-bormann-appsawg-cbor-merge-patch-00

Abstract

   This specification defines the CBOR merge patch format and processing
   rules, as an analog to the JSON merge patch format defined in RFC
   7396.  The merge patch format is primarily intended for use with the
   HTTP PATCH method and potential related CoAP methods as a means of
   describing a set of modifications to a target resource's content.

   This specification also defines how a JSON merge patch document is
   applied to a CBOR data item and vice versa.

Status of This Memo

   This Internet-Draft is submitted 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 September 22, 2016.

Copyright Notice

   Copyright (c) 2016 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



Bormann & van der Stok Expires September 22, 2016               [Page 1]


Internet-Draft              CBOR Merge Patch                  March 2016


   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.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Processing Merge Patch Documents  . . . . . . . . . . . . . .   4
   3.  Example . . . . . . . . . . . . . . . . . . . . . . . . . . .   4
   4.  Interoperation of JSON merge patch and CBOR merge patch . . .   5
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .   7
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   7
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .   7
     7.2.  Informative References  . . . . . . . . . . . . . . . . .   7
   Appendix A.  Example Test Cases . . . . . . . . . . . . . . . . .   9
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  10
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  10

1.  Introduction

   The Concise Binary Object Representation (CBOR, [RFC7049]) defines a
   binary representation for data that can be described using an
   extension of the JSON data model [RFC7159].  The JSON merge-patch
   [RFC7396] format was designed to represent updates ("patches") to
   data that is structured according to the JSON data model.

   This specification defines the CBOR merge patch document format,
   processing rules, and associated MIME media type identifier.  The
   merge patch format is primarily intended for use as a means of
   describing a set of modifications to a target resource's content,
   with the HTTP PATCH method [RFC5789] or with potential PATCH-like
   CoAP [RFC7252] methods to be defined [I-D-vanderstok-core-etch].

   A CBOR merge patch document describes changes to be made to a target
   CBOR document using a syntax that closely mimics the document being
   modified.  Recipients of a merge patch document determine the exact
   set of changes being requested by comparing the content of the
   provided patch against the current content of the target document.
   If the provided merge patch contains members that do not appear
   within the target, those members are added.  If the target does
   contain the member, the value is replaced.  Null values in the merge
   patch are given special meaning to indicate the removal of existing
   values in the target.






Bormann & van der Stok Expires September 22, 2016               [Page 2]


Internet-Draft              CBOR Merge Patch                  March 2016


   For example, given the following original CBOR document (as with all
   following examples, the CBOR data is shown in CBOR diagnostic
   notation):

       {
         "a": h'4711',
         3: {
           "d": 1(1454280297),
           "f": "g"
         }
       }

   Changing the value of "a" and removing "f" can be achieved by
   sending:

       PATCH /target HTTP/1.1
       Host: example.org
       Content-Type: application/merge-patch+cbor

       {
         "a": "now is text",
         3: {
           "f": null
         }
       }

   When applied to the target resource, the value of the "a" member is
   replaced with "now is text" and "f" is removed, leaving the remaining
   content untouched.

   This design means that merge patch documents are suitable for
   describing modifications to CBOR documents that primarily use maps
   for their structure and do not make use of explicit null values.  The
   merge patch format is not appropriate for all CBOR structures.

      Discussion: CBOR has more simple types than JSON.  We could define
      another simple type (beyond null) that is used for removing map
      entries.  The current proposal does not do this as map entries
      with a null value are equivalent to not having the map entry in
      many CBOR structures.

   This design also means that applying a CBOR merge patch is an
   idempotent operation: Applying the same patch again to the result of
   applying it first yields exactly the same result.  This property may
   be useful in the context of a potential CoAP idempotent PATCH method
   (iPATCH in [I-D-vanderstok-core-etch]).





Bormann & van der Stok Expires September 22, 2016               [Page 3]


Internet-Draft              CBOR Merge Patch                  March 2016


2.  Processing Merge Patch Documents

   CBOR merge patch documents describe, by example, a set of changes
   that are to be made to a target resource.  Recipients of merge patch
   documents are responsible for comparing the merge patch with the
   current content of the target resource to determine the specific set
   of change operations to be applied to the target.

   To apply the merge patch document to a target resource, the system
   realizes the effect of the following function, described in
   pseudocode.  For this description, the function is called MergePatch,
   and it takes two arguments: the target resource document and the
   merge patch document.  The Target argument can be any CBOR value or
   undefined.  The Patch argument can be any CBOR value.

     define MergePatch(Target, Patch):
       if Patch is a map:
         if Target is not a map:
           Target = {} # Ignore the contents and set it to an empty Map
         for each Name/Value pair in Patch:
           if Value is null:
             if Name exists in Target:
               remove the Name/Value pair from Target
           else:
             Target[Name] = MergePatch(Target[Name], Value)
         return Target
       else:
         return Patch

   There are a few things to note about the function.  If the patch is
   anything other than a map, the result will always be to replace the
   entire target with the entire patch.  Also, it is not possible to
   patch part of a target that is not a map, such as to replace just
   some of the values in an array.

   The MergePatch operation is defined to operate at the level of data
   items, not at the level of binary representation.  There is no
   expectation that the MergePatch operation will preserve features at
   the textual-representation level such as member ordering or number
   precision beyond what is available in the target's implementation,
   and so forth.

3.  Example

   Given the following example CBOR document:






Bormann & van der Stok Expires September 22, 2016               [Page 4]


Internet-Draft              CBOR Merge Patch                  March 2016


       {
         "title": "Goodbye!",
         "author" : {
           "givenName" : "John",
           "familyName" : "Doe"
         },
         "tags": ["example", "sample"],
         "content": "This will be unchanged"
       }

   A user agent wishing to change the value of the "title" member from
   "Goodbye!" to the value "Hello!", add a new "phoneNumber" member,
   remove the "familyName" member from the "author" map, and replace the
   "tags" array so that it doesn't include the word "sample" would send
   the following request:

       PATCH /my/resource HTTP/1.1
       Host: example.org
       Content-Type: application/merge-patch+cbor

       {
         "title": "Hello!",
         "phoneNumber": "+01-123-456-7890",
         "author": {
           "familyName": null
         },
         "tags": ["example"]
       }

   The resulting CBOR document would be:

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

4.  Interoperation of JSON merge patch and CBOR merge patch

   A CBOR merge patch document is applied to a JSON document by first
   converting it into a JSON document using the rules in Section 4.1 of
   [RFC7049] and then applying the result as a JSON merge-patch
   document.  This only works very well if the conversion from CBOR
   values in the CBOR merge patch document to JSON values results in a



Bormann & van der Stok Expires September 22, 2016               [Page 5]


Internet-Draft              CBOR Merge Patch                  March 2016


   useful JSON merge patch document.  (This is trivially the case if all
   the data in the CBOR merge patch document conform to the unextended
   JSON data model.  The effects of the conversions may also be desired,
   e.g. to patch a JSON map entry with the key "1" by supplying an
   integer 1 as the key in the patch, or to supply a base64url value in
   the form of an unencoded binary string.)

   A JSON merge patch document is applied to a CBOR data items by first
   converting it into a CBOR data item using the rules in Section 4.2 of
   [RFC7049] and then applying the result as a CBOR merge patch
   document.  The conversion always leads to a valid CBOR merge patch
   document, but the set of such documents that can be generated from
   JSON of course cannot create all possible outcomes that may be
   desired when patching a CBOR data item.

5.  IANA Considerations

   The Internet media type [RFC6838] for CBOR merge patch is
   application/merge-patch+cbor.

      Type name: application

      Subtype name: merge-patch+cbor

      Required parameters: None

      Optional parameters: None

      Encoding considerations: Resources that use the "application/
      merge-patch+cbor" media type are required to conform to the
      "application/cbor" media type and are therefore subject to the
      same encoding considerations specified in Section 7.3 of
      [RFC7049].

      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






Bormann & van der Stok Expires September 22, 2016               [Page 6]


Internet-Draft              CBOR Merge Patch                  March 2016


         File extension(s): N/A



         Macintosh file type code(s): N/A

      Person & email address to contact for further information: IESG

      Intended usage: COMMON

      Restrictions on usage: None

      Author: Carsten Bormann <cabo@tzi.org>

      Change controller: IESG

6.  Security Considerations

   The security considerations of [RFC7049] and [RFC7396] apply.

7.  References

7.1.  Normative References

   [RFC7049]  Bormann, C. and P. Hoffman, "Concise Binary Object
              Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
              October 2013, <http://www.rfc-editor.org/info/rfc7049>.

7.2.  Informative References

   [I-D-vanderstok-core-etch]
              van der Stok, P., Bormann, C., and A. Sehgal, "Patch and
              Fetch Methods for Constrained Application Protocol
              (CoAP)", March 2016.

   [RFC5789]  Dusseault, L. and J. Snell, "PATCH Method for HTTP",
              RFC 5789, DOI 10.17487/RFC5789, March 2010,
              <http://www.rfc-editor.org/info/rfc5789>.

   [RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
              Specifications and Registration Procedures", BCP 13,
              RFC 6838, DOI 10.17487/RFC6838, January 2013,
              <http://www.rfc-editor.org/info/rfc6838>.

   [RFC7159]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
              2014, <http://www.rfc-editor.org/info/rfc7159>.




Bormann & van der Stok Expires September 22, 2016               [Page 7]


Internet-Draft              CBOR Merge Patch                  March 2016


   [RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
              Application Protocol (CoAP)", RFC 7252,
              DOI 10.17487/RFC7252, June 2014,
              <http://www.rfc-editor.org/info/rfc7252>.

   [RFC7396]  Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396,
              DOI 10.17487/RFC7396, October 2014,
              <http://www.rfc-editor.org/info/rfc7396>.











































Bormann & van der Stok Expires September 22, 2016               [Page 8]


Internet-Draft              CBOR Merge Patch                  March 2016


Appendix A.  Example Test Cases

   ORIGINAL        PATCH            RESULT
   ------------------------------------------
   {"a":"b"}       {"a":"c"}       {"a":"c"}

   {"a":"b"}       {"b":"c"}       {"a":"b",
                                    "b":"c"}

   {"a":"b"}       {"a":null}      {}

   {"a":"b",       {"a":null}      {"b":"c"}
    "b":"c"}

   {"a":["b"]}     {"a":"c"}       {"a":"c"}

   {"a":"c"}       {"a":["b"]}     {"a":["b"]}

   {"a": {         {"a": {         {"a": {
     "b": "c"}       "b": "d",       "b": "d"
   }                 "c": null}      }
                   }               }

   {"a": [         {"a": [1]}      {"a": [1]}
     {"b":"c"}
    ]
   }

   ["a","b"]       ["c","d"]       ["c","d"]

   {"a":"b"}       ["c"]           ["c"]

   {"a":"foo"}     null            null

   {"a":"foo"}     "bar"           "bar"

   {"e":null}      {"a":1}         {"e":null,
                                    "a":1}

   [1,2]           {"a":"b",       {"a":"b"}
                    "c":null}

   {}              {"a":            {"a":
                    {"bb":           {"bb":
                     {"ccc":          {}}}
                      null}}}





Bormann & van der Stok Expires September 22, 2016               [Page 9]


Internet-Draft              CBOR Merge Patch                  March 2016


Acknowledgments

   Paul Hoffman and James Snell wrote RFC 7396, from which this document
   liberally borrows most of its text.

Authors' Addresses

   Carsten Bormann
   Universitaet Bremen TZI
   Postfach 330440
   Bremen  D-28359
   Germany

   Phone: +49-421-218-63921
   EMail: cabo@tzi.org


   Peter van der Stok
   Consultant

   EMail: consultancy@vanderstok.org






























Bormann & van der Stok Expires September 22, 2016              [Page 10]