idnits 2.17.1 draft-ietf-appsawg-json-merge-patch-07.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 (August 21, 2014) is 3529 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 140, but not defined -- Looks like a reference, but probably isn't: '1' on line 318 -- Looks like a reference, but probably isn't: '2' on line 318 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Applications Area Working Group P. Hoffman 3 Internet-Draft VPN Consortium 4 Intended status: Standards Track J. Snell 5 Expires: February 22, 2015 6 August 21, 2014 8 JSON Merge Patch 9 draft-ietf-appsawg-json-merge-patch-07 11 Abstract 13 This specification defines the JSON merge patch format and processing 14 rules. The merge patch format is primarily intended for use with the 15 HTTP PATCH method as a means of describing a set of modifications to 16 a target resource's content. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on February 22, 2015. 35 Copyright Notice 37 Copyright (c) 2014 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Processing Merge Patch Documents . . . . . . . . . . . . . . 3 54 3. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 56 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 57 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 58 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 7.1. Normative References . . . . . . . . . . . . . . . . . . 6 60 7.2. Informative References . . . . . . . . . . . . . . . . . 7 61 Appendix A. Example Test Cases . . . . . . . . . . . . . . . . . 7 62 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 64 1. Introduction 66 This specification defines the JSON merge patch document format, 67 processing rules, and associated MIME media type identifier. The 68 merge patch format is primarily intended for use with the HTTP PATCH 69 method [RFC5789] as a means of describing a set of modifications to a 70 target resource's content. 72 A JSON merge patch document describes changes to be made to a target 73 JSON document using a syntax that closely mimics the document being 74 modified. Recipients of a merge patch document determine the exact 75 set of changes being requested by comparing the content of the 76 provided patch against the current content of the target document. 77 If the provided merge patch contains members that do not appear 78 within the target, those members are added. If the target does 79 contain the member, the value is replaced. Null values in the merge 80 patch are given special meaning to indicate the removal of existing 81 values in the target. 83 For example, given the following original JSON document: 85 { 86 "a": "b", 87 "c": { 88 "d": "e", 89 "f": "g" 90 } 91 } 93 Changing the value of "a" and removing "f" can be achieved by 94 sending: 96 PATCH /target HTTP/1.1 97 Host: example.org 98 Content-Type: application/merge-patch+json 100 { 101 "a":"z", 102 "c": { 103 "f": null 104 } 105 } 107 When applied to the target resource, the value of the "a" member is 108 replaced with "z" and "f" is removed, leaving the remaining content 109 untouched. 111 This design means that merge patch documents are suitable for 112 describing modifications to JSON documents that primarily use objects 113 for their structure and do not make use of explicit null values. The 114 merge patch format is not appropriate for all JSON syntaxes. 116 2. Processing Merge Patch Documents 118 JSON merge patch documents describe, by example, a set of changes 119 that are to be made to a target resource. Recipients of merge patch 120 documents are responsible for comparing the merge patch with the 121 current content of the target resource to determine the specific set 122 of change operations to be applied to the target. 124 To apply the merge patch document to a target resource, the system 125 realizes the effect of the following function, described in 126 pseudocode. For this description, the function is called MergePatch, 127 and it takes two arguments: the target resource document and the 128 merge patch document. The Target argument can be any JSON value, or 129 undefined. The Patch argument can be any JSON value. 131 define MergePatch(Target, Patch): 132 if Patch is an Object: 133 if Target is not an Object: 134 Target = {} # Ignore the contents and set it to an empty Object 135 for each Name/Value pair in Patch: 136 if Value is null: 137 if Name exists in Target: 138 remove the Name/Value pair from Target 139 else: 140 Target[Name] = MergePatch(Target[Name], Value) 141 return Target 142 else: 143 return Patch 145 There are a few things to note about the function. If the patch is 146 anything other than an object, the result will always be to replace 147 the entire target with the entire patch. Also, it is not possible to 148 patch part of a target that is not an object, such as to replace just 149 some if the values in an array. 151 The MergePatch operation is defined to operate at the level of data 152 items, not at the level of textual representation. There is no 153 expectation that the MergePatch operation will preserve textual 154 representation-level features such as white space, member ordering, 155 number precision beyond what is available in the target's 156 implementation, and so forth. In addition, even if the target 157 implementation allows multiple name/value pairs with the same name, 158 the result of the patch operation on such objects is not defined. 160 3. Example 162 For example, given the following example JSON document: 164 { 165 "title": "Goodbye!", 166 "author" : { 167 "givenName" : "John", 168 "familyName" : "Doe" 169 }, 170 "tags":[ "example", "sample" ], 171 "content": "This will be unchanged" 172 } 174 A user-agent wishing to change the value of the "title" member from 175 "Goodbye!" to the value "Hello!", add a new "phoneNumber" member, 176 remove the "familyName" member from the "author" object, and replace 177 the "tags" Array so that it doesn't include the word "sample", would 178 send the following request: 180 PATCH /my/resource HTTP/1.1 181 Host: example.org 182 Content-Type: application/merge-patch+json 184 { 185 "title": "Hello!", 186 "phoneNumber": "+01-123-456-7890", 187 "author": { 188 "familyName": null 189 }, 190 "tags": [ "example" ] 191 } 193 The resulting JSON document would be: 195 { 196 "title": "Hello!", 197 "author" : { 198 "givenName" : "John" 199 }, 200 "tags": [ "example" ], 201 "content": "This will be unchanged", 202 "phoneNumber": "+01-123-456-7890" 203 } 205 4. IANA Considerations 207 This specification registers the following additional MIME Media 208 Types: 210 Type name: application 212 Subtype name: merge-patch+json 214 Required parameters: None 216 Optional parameters: None 218 Encoding considerations: Resources that use the "application/ 219 merge-patch+json" media type are required to conform to the 220 "application/json" Media Type and are therefore subject to the 221 same encoding considerations specified in Section 8 of [RFC7159]. 223 Security considerations: As defined in this specification 225 Published specification: This specification. 227 Applications that use this media type: None currently known. 229 Additional information: 231 Magic number(s): N/A 233 File extension(s): N/A 235 Macintosh file type code(s): TEXT 237 Person & email address to contact for further information: IESG 239 Intended usage: COMMON 241 Restrictions on usage: None. 243 Author: James M Snell 245 Change controller: IESG 247 5. Security Considerations 249 The "application/merge-patch+json" Media Type allows user agents to 250 indicate their intention that the server determine the specific set 251 of change operations to be applied to a target resource. As such, it 252 is the server's responsibility to determine the appropriateness of 253 any given change as well as the user agent's authorization to request 254 such changes. How such determinations are made is considered out of 255 the scope of this specification. 257 All of the the security considerations discussed in Section 5 of 258 [RFC5789] apply to all uses of the HTTP PATCH method with the 259 "application/merge-patch+json" Media Type. 261 6. Acknowledgements 263 Many people contributed significant ideas to this document. These 264 people include, but are not limited to, James Manger, Matt Miller, 265 Carsten Bormann, and Bjoern Hoehrmann, Pete Resnick, and Richard 266 Barnes. 268 7. References 270 7.1. Normative References 272 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 273 Interchange Format", RFC 7159, March 2014. 275 7.2. Informative References 277 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 278 5789, March 2010. 280 Appendix A. Example Test Cases 281 ORIGINAL PATCH RESULT 282 ------------------------------------------ 283 {"a":"b"} {"a":"c"} {"a":"c"} 285 {"a":"b"} {"b":"c"} {"a":"b", 286 "b":"c"} 288 {"a":"b"} {"a":null} {} 290 {"a":"b", {"a":null} {"b":"c"} 291 "b":"c"} 293 {"a":["b"]} {"a":"c"} {"a":"c"} 295 {"a":"c"} {"a":["b"]} {"a":["b"]} 297 {"a": { {"a": { {"a": { 298 "b": "c"} "b": "d", "b": "d" 299 } "c": null} } 300 } } 302 {"a": [ {"a": [1]} {"a": [1]} 303 {"b":"c"} 304 ] 305 } 307 ["a","b"] ["c","d"] ["c","d"] 309 {"a":"b"} ["c"] ["c"] 311 {"a":"foo"} null null 313 {"a":"foo"} "bar" "bar" 315 {"e":null} {"a":1} {"e":null, 316 "a":1} 318 [1,2] {"a":"b", {"a":"b"} 319 "c":null} 321 {} {"a": {"a": 322 {"bb": {"bb": 323 {"ccc": {}}} 324 null}}} 326 Authors' Addresses 328 Paul Hoffman 329 VPN Consortium 331 Email: paul.hoffman@vpnc.org 333 James M Snell 335 Email: jasnell@gmail.com