idnits 2.17.1 draft-wilde-xml-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 : ---------------------------------------------------------------------------- ** There are 5 instances of too long lines in the document, the longest one being 13 characters in excess of 72. ** The abstract seems to contain references ([8], [9]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 14, 2013) is 4120 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: '4' is defined on line 231, but no explicit reference was found in the text == Unused Reference: '5' is defined on line 235, but no explicit reference was found in the text ** Obsolete normative reference: RFC 3023 (ref. '1') (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 4288 (ref. '3') (Obsoleted by RFC 6838) -- Obsolete informational reference (is this intentional?): RFC 2616 (ref. '7') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 4 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Wilde 3 Internet-Draft EMC 4 Intended status: Standards Track M. Nottingham 5 Expires: July 18, 2013 Akamai 6 January 14, 2013 8 A Media Type for XML Patch Operations 9 draft-wilde-xml-patch-00 11 Abstract 13 The XML Patch media type "application/xml-patch" defines an XML 14 document structure for expressing a sequence of patch operations that 15 are applied to an XML document. The XML Patch document format's 16 foundations are defined in RFC 5261, this specification defines a 17 document format and a media type registration, so that XML Patch 18 documents can be labeled with a media type, for example in HTTP 19 conversations. 21 Note to Readers 23 This draft should be discussed on the apps-discuss mailing list [8]. 25 Online access to all versions and files is available at github [9]. 27 Status of this Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on July 18, 2013. 44 Copyright Notice 46 Copyright (c) 2013 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 3 63 3. Patch Document Format . . . . . . . . . . . . . . . . . . . . . 4 64 4. Patch Examples . . . . . . . . . . . . . . . . . . . . . . . . 5 65 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 66 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 6.1. Normative References . . . . . . . . . . . . . . . . . . . 6 68 6.2. Informative References . . . . . . . . . . . . . . . . . . 6 69 Appendix A. XSD from RFC 5261 . . . . . . . . . . . . . . . . . . 7 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 72 1. Introduction 74 The Extensible Markup Language (XML) [1] is a common format for the 75 exchange and storage of structured data. HTTP PATCH [6] extends HTTP 76 [7] with a method to perform partial modifications to resources. 77 HTTP PATCH requires that patch documents are being sent along with 78 the request, and it is therefore useful if there are standardized 79 patch document formats (identified by media types) for popular media 80 types. 82 The XML Patch media type "application/xml-patch" is an XML document 83 structure for expressing a sequence of operations to apply to a 84 target XML document, suitable for use with the HTTP PATCH method. 85 Servers can freely choose which patch formats they want to accept, 86 and "application/xml-patch" could be a simple default format that can 87 be used unless a server decides to use a different (maybe more 88 sophisticated) patch format for XML. 90 The format for patch documents is based on the XML Patch Framework 91 defined in RFC 5261 [2]. While RFC 5261 does define a concrete 92 syntax as well as the media type "application/patch-ops-error+xml" 93 for error documents, it only defines XSD types for patch operations, 94 and thus the concrete document format and the media type for patch 95 operations are defined in an XSD defined in this specification. 97 2. IANA Considerations 99 The Internet media type [3] for an XML Patch Document is application/ 100 xml-patch. 102 Type name: application 104 Subtype name: xml-patch 106 Required parameters: none 108 Optional parameters: Same as charset parameter for the media type 109 "application/xml" as specified in RFC 3023 [1]. 111 Encoding considerations: Same as encoding considerations of media 112 type "application/xml" as specified in RFC 3023 [1]. 114 Security considerations: This media type has all of the security 115 considerations described in RFC 3023 [1] and RFC 5261 [2], plus 116 those listed in Section 5. 118 Interoperability considerations: N/A 120 Published specification: RFC XXXX 122 Applications that use this media type: Applications that 123 manipulate XML documents. 125 Additional information: 127 Magic number(s): N/A 129 File extension(s): XML documents should use ".xml" as the file 130 extension. 132 Macintosh file type code(s): TEXT 134 Person & email address to contact for further information: Erik 135 Wilde 137 Intended usage: COMMON 139 Restrictions on usage: none 141 Author: Erik Wilde 143 Change controller: IETF 145 3. Patch Document Format 147 The XML patch document format is based on a simple schema that uses a 148 "patch" element as the document element, and allows a arbitrary 149 sequence of "add", "remove", and "replace" elements as the children 150 of the document element. These children follow the semantics defined 151 in RFC 5261, which means that each element is treated as an 152 individual patch operation, and the result of each patch operation is 153 a patched XML document that is the target XML document for the next 154 patch operation. 156 The following example patch document uses the example from RFC 5261, 157 and simply uses a "patch" element and a new XML namespace. It shows 158 the general structure of an XML patch document, as well as an example 159 for each operation. 161 164 165 166 167 168 169 170 Patched doc 171 172 new attr 173 175 As this example demonstrates, both the document element "patch" and 176 the patch operation elements are in the same XML namespace. This is 177 the result of RFC 5261 only defining types for the patch operation 178 elements, which then can be reused in schemas to define concrete 179 patch elements. 181 RFC 5261 defines an XML Schema (XSD) for the patch operation types, 182 which is included for reference Appendix A. The normative version of 183 this schema is the one given in RFC 5261. The following schema for 184 the XML Patch media type is based on the types defined in RFC 5261, 185 which are imported as "rfc5261.xsd" in the following schema. The 186 schema defines a "patch" document element, and then allows an 187 unlimited (and possible empty) sequence of the "add", "remove", and 188 "replace" operation elements, which are directly based on the 189 respective types from the schema defined in RFC 5261. 190 192 193 194 195 196 197 198 199 200 201 202 204 4. Patch Examples 206 Since the semantics of the XML patch operations are defined by RFC 207 5261, please refer to the numerous examples in that specification for 208 concrete XML patch document examples. Most importantly, the examples 209 in RFC 5261 can be taken literally as examples for the XML Patch 210 media type, as long as it is assumed that the XML namespace for the 211 operation elements in these examples is the URI "urn:ietf:rfc:XXXX". 213 5. Security Considerations 215 ... 217 6. References 219 6.1. Normative References 221 [1] Murata, M., St. Laurent, S., and D. Kohn, "XML Media Types", 222 RFC 3023, January 2001. 224 [2] Urpalainen, J., "An Extensible Markup Language (XML) Patch 225 Operations Framework Utilizing XML Path Language (XPath) 226 Selectors", RFC 5261, September 2008. 228 [3] Freed, N. and J. Klensin, "Media Type Specifications and 229 Registration Procedures", BCP 13, RFC 4288, December 2005. 231 [4] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 232 Extensions (MIME) Part One: Format of Internet Message Bodies", 233 RFC 2045, November 1996. 235 [5] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 236 Extensions (MIME) Part Two: Media Types", RFC 2046, 237 November 1996. 239 6.2. Informative References 241 [6] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, 242 March 2010. 244 [7] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 245 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- 246 HTTP/1.1", RFC 2616, June 1999. 248 URIs 250 [8] 252 [9] 254 Appendix A. XSD from RFC 5261 256 For reference, this section contains a copy of the XSD defining the 257 add, replace, and remove types in RFC 5261 [2]. This section is 258 informational only, and the definitive version of the schema is the 259 one listed in RFC 5261. 260 261 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 ]> 281 285 286 287 289 290 292 293 294 296 297 299 300 301 302 303 304 305 307 308 309 310 311 313 314 315 316 317 319 320 322 323 324 325 326 328 329 330 331 332 334 335 336 337 338 340 341 342 343 344 345 346 348 349 350 351 353 355 Authors' Addresses 357 Erik Wilde 358 EMC 360 Email: erik.wilde@emc.com 362 Mark Nottingham 363 Akamai 365 Email: mnot@mnot.net