Internet DRAFT - draft-bormann-appsawg-cbor-merge-patch
draft-bormann-appsawg-cbor-merge-patch
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]
