idnits 2.17.1 draft-bormann-appsawg-cbor-merge-patch-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 21, 2016) is 2951 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'Name' is mentioned on line 166, but not defined -- Looks like a reference, but probably isn't: '1' on line 373 -- Looks like a reference, but probably isn't: '2' on line 373 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Applications Area Working Group C. Bormann 3 Internet-Draft Universitaet Bremen TZI 4 Intended status: Standards Track P. van der Stok 5 Expires: September 22, 2016 Consultant 6 March 21, 2016 8 CBOR Merge Patch 9 draft-bormann-appsawg-cbor-merge-patch-00 11 Abstract 13 This specification defines the CBOR merge patch format and processing 14 rules, as an analog to the JSON merge patch format defined in RFC 15 7396. The merge patch format is primarily intended for use with the 16 HTTP PATCH method and potential related CoAP methods as a means of 17 describing a set of modifications to a target resource's content. 19 This specification also defines how a JSON merge patch document is 20 applied to a CBOR data item and vice versa. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on September 22, 2016. 39 Copyright Notice 41 Copyright (c) 2016 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. Processing Merge Patch Documents . . . . . . . . . . . . . . 4 58 3. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 4. Interoperation of JSON merge patch and CBOR merge patch . . . 5 60 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 61 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 62 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 63 7.1. Normative References . . . . . . . . . . . . . . . . . . 7 64 7.2. Informative References . . . . . . . . . . . . . . . . . 7 65 Appendix A. Example Test Cases . . . . . . . . . . . . . . . . . 9 66 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 10 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 69 1. Introduction 71 The Concise Binary Object Representation (CBOR, [RFC7049]) defines a 72 binary representation for data that can be described using an 73 extension of the JSON data model [RFC7159]. The JSON merge-patch 74 [RFC7396] format was designed to represent updates ("patches") to 75 data that is structured according to the JSON data model. 77 This specification defines the CBOR merge patch document format, 78 processing rules, and associated MIME media type identifier. The 79 merge patch format is primarily intended for use as a means of 80 describing a set of modifications to a target resource's content, 81 with the HTTP PATCH method [RFC5789] or with potential PATCH-like 82 CoAP [RFC7252] methods to be defined [I-D-vanderstok-core-etch]. 84 A CBOR merge patch document describes changes to be made to a target 85 CBOR document using a syntax that closely mimics the document being 86 modified. Recipients of a merge patch document determine the exact 87 set of changes being requested by comparing the content of the 88 provided patch against the current content of the target document. 89 If the provided merge patch contains members that do not appear 90 within the target, those members are added. If the target does 91 contain the member, the value is replaced. Null values in the merge 92 patch are given special meaning to indicate the removal of existing 93 values in the target. 95 For example, given the following original CBOR document (as with all 96 following examples, the CBOR data is shown in CBOR diagnostic 97 notation): 99 { 100 "a": h'4711', 101 3: { 102 "d": 1(1454280297), 103 "f": "g" 104 } 105 } 107 Changing the value of "a" and removing "f" can be achieved by 108 sending: 110 PATCH /target HTTP/1.1 111 Host: example.org 112 Content-Type: application/merge-patch+cbor 114 { 115 "a": "now is text", 116 3: { 117 "f": null 118 } 119 } 121 When applied to the target resource, the value of the "a" member is 122 replaced with "now is text" and "f" is removed, leaving the remaining 123 content untouched. 125 This design means that merge patch documents are suitable for 126 describing modifications to CBOR documents that primarily use maps 127 for their structure and do not make use of explicit null values. The 128 merge patch format is not appropriate for all CBOR structures. 130 Discussion: CBOR has more simple types than JSON. We could define 131 another simple type (beyond null) that is used for removing map 132 entries. The current proposal does not do this as map entries 133 with a null value are equivalent to not having the map entry in 134 many CBOR structures. 136 This design also means that applying a CBOR merge patch is an 137 idempotent operation: Applying the same patch again to the result of 138 applying it first yields exactly the same result. This property may 139 be useful in the context of a potential CoAP idempotent PATCH method 140 (iPATCH in [I-D-vanderstok-core-etch]). 142 2. Processing Merge Patch Documents 144 CBOR merge patch documents describe, by example, a set of changes 145 that are to be made to a target resource. Recipients of merge patch 146 documents are responsible for comparing the merge patch with the 147 current content of the target resource to determine the specific set 148 of change operations to be applied to the target. 150 To apply the merge patch document to a target resource, the system 151 realizes the effect of the following function, described in 152 pseudocode. For this description, the function is called MergePatch, 153 and it takes two arguments: the target resource document and the 154 merge patch document. The Target argument can be any CBOR value or 155 undefined. The Patch argument can be any CBOR value. 157 define MergePatch(Target, Patch): 158 if Patch is a map: 159 if Target is not a map: 160 Target = {} # Ignore the contents and set it to an empty Map 161 for each Name/Value pair in Patch: 162 if Value is null: 163 if Name exists in Target: 164 remove the Name/Value pair from Target 165 else: 166 Target[Name] = MergePatch(Target[Name], Value) 167 return Target 168 else: 169 return Patch 171 There are a few things to note about the function. If the patch is 172 anything other than a map, the result will always be to replace the 173 entire target with the entire patch. Also, it is not possible to 174 patch part of a target that is not a map, such as to replace just 175 some of the values in an array. 177 The MergePatch operation is defined to operate at the level of data 178 items, not at the level of binary representation. There is no 179 expectation that the MergePatch operation will preserve features at 180 the textual-representation level such as member ordering or number 181 precision beyond what is available in the target's implementation, 182 and so forth. 184 3. Example 186 Given the following example CBOR document: 188 { 189 "title": "Goodbye!", 190 "author" : { 191 "givenName" : "John", 192 "familyName" : "Doe" 193 }, 194 "tags": ["example", "sample"], 195 "content": "This will be unchanged" 196 } 198 A user agent wishing to change the value of the "title" member from 199 "Goodbye!" to the value "Hello!", add a new "phoneNumber" member, 200 remove the "familyName" member from the "author" map, and replace the 201 "tags" array so that it doesn't include the word "sample" would send 202 the following request: 204 PATCH /my/resource HTTP/1.1 205 Host: example.org 206 Content-Type: application/merge-patch+cbor 208 { 209 "title": "Hello!", 210 "phoneNumber": "+01-123-456-7890", 211 "author": { 212 "familyName": null 213 }, 214 "tags": ["example"] 215 } 217 The resulting CBOR document would be: 219 { 220 "title": "Hello!", 221 "author" : { 222 "givenName" : "John" 223 }, 224 "tags": ["example"], 225 "content": "This will be unchanged", 226 "phoneNumber": "+01-123-456-7890" 227 } 229 4. Interoperation of JSON merge patch and CBOR merge patch 231 A CBOR merge patch document is applied to a JSON document by first 232 converting it into a JSON document using the rules in Section 4.1 of 233 [RFC7049] and then applying the result as a JSON merge-patch 234 document. This only works very well if the conversion from CBOR 235 values in the CBOR merge patch document to JSON values results in a 236 useful JSON merge patch document. (This is trivially the case if all 237 the data in the CBOR merge patch document conform to the unextended 238 JSON data model. The effects of the conversions may also be desired, 239 e.g. to patch a JSON map entry with the key "1" by supplying an 240 integer 1 as the key in the patch, or to supply a base64url value in 241 the form of an unencoded binary string.) 243 A JSON merge patch document is applied to a CBOR data items by first 244 converting it into a CBOR data item using the rules in Section 4.2 of 245 [RFC7049] and then applying the result as a CBOR merge patch 246 document. The conversion always leads to a valid CBOR merge patch 247 document, but the set of such documents that can be generated from 248 JSON of course cannot create all possible outcomes that may be 249 desired when patching a CBOR data item. 251 5. IANA Considerations 253 The Internet media type [RFC6838] for CBOR merge patch is 254 application/merge-patch+cbor. 256 Type name: application 258 Subtype name: merge-patch+cbor 260 Required parameters: None 262 Optional parameters: None 264 Encoding considerations: Resources that use the "application/ 265 merge-patch+cbor" media type are required to conform to the 266 "application/cbor" media type and are therefore subject to the 267 same encoding considerations specified in Section 7.3 of 268 [RFC7049]. 270 Security considerations: As defined in this specification 272 Published specification: This specification. 274 Applications that use this media type: None currently known. 276 Additional information: 278 Magic number(s): N/A 279 File extension(s): N/A 281 Macintosh file type code(s): N/A 283 Person & email address to contact for further information: IESG 285 Intended usage: COMMON 287 Restrictions on usage: None 289 Author: Carsten Bormann 291 Change controller: IESG 293 6. Security Considerations 295 The security considerations of [RFC7049] and [RFC7396] apply. 297 7. References 299 7.1. Normative References 301 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 302 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 303 October 2013, . 305 7.2. Informative References 307 [I-D-vanderstok-core-etch] 308 van der Stok, P., Bormann, C., and A. Sehgal, "Patch and 309 Fetch Methods for Constrained Application Protocol 310 (CoAP)", March 2016. 312 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 313 RFC 5789, DOI 10.17487/RFC5789, March 2010, 314 . 316 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 317 Specifications and Registration Procedures", BCP 13, 318 RFC 6838, DOI 10.17487/RFC6838, January 2013, 319 . 321 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 322 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 323 2014, . 325 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 326 Application Protocol (CoAP)", RFC 7252, 327 DOI 10.17487/RFC7252, June 2014, 328 . 330 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 331 DOI 10.17487/RFC7396, October 2014, 332 . 334 Appendix A. Example Test Cases 336 ORIGINAL PATCH RESULT 337 ------------------------------------------ 338 {"a":"b"} {"a":"c"} {"a":"c"} 340 {"a":"b"} {"b":"c"} {"a":"b", 341 "b":"c"} 343 {"a":"b"} {"a":null} {} 345 {"a":"b", {"a":null} {"b":"c"} 346 "b":"c"} 348 {"a":["b"]} {"a":"c"} {"a":"c"} 350 {"a":"c"} {"a":["b"]} {"a":["b"]} 352 {"a": { {"a": { {"a": { 353 "b": "c"} "b": "d", "b": "d" 354 } "c": null} } 355 } } 357 {"a": [ {"a": [1]} {"a": [1]} 358 {"b":"c"} 359 ] 360 } 362 ["a","b"] ["c","d"] ["c","d"] 364 {"a":"b"} ["c"] ["c"] 366 {"a":"foo"} null null 368 {"a":"foo"} "bar" "bar" 370 {"e":null} {"a":1} {"e":null, 371 "a":1} 373 [1,2] {"a":"b", {"a":"b"} 374 "c":null} 376 {} {"a": {"a": 377 {"bb": {"bb": 378 {"ccc": {}}} 379 null}}} 381 Acknowledgments 383 Paul Hoffman and James Snell wrote RFC 7396, from which this document 384 liberally borrows most of its text. 386 Authors' Addresses 388 Carsten Bormann 389 Universitaet Bremen TZI 390 Postfach 330440 391 Bremen D-28359 392 Germany 394 Phone: +49-421-218-63921 395 EMail: cabo@tzi.org 397 Peter van der Stok 398 Consultant 400 EMail: consultancy@vanderstok.org