idnits 2.17.1 draft-ietf-vcarddav-webdav-mkcol-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) 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 : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC4918, but the abstract doesn't seem to mention this, which it should. -- The draft header indicates that this document updates RFC4791, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC4791, updated by this document, for RFC5378 checks: 2004-06-24) (Using the creation date from RFC4918, updated by this document, for RFC5378 checks: 2002-02-20) -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 18, 2009) is 5363 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) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Daboo 3 Internet-Draft Apple Inc. 4 Updates: 4791, 4918 August 18, 2009 5 (if approved) 6 Intended status: Standards Track 7 Expires: February 19, 2010 9 Extended MKCOL for WebDAV 10 draft-ietf-vcarddav-webdav-mkcol-06 12 Status of This Memo 14 This Internet-Draft is submitted to IETF in full conformance with the 15 provisions of BCP 78 and BCP 79. This document may contain material 16 from IETF Documents or IETF Contributions published or made publicly 17 available before November 10, 2008. The person(s) controlling the 18 copyright in some of this material may not have granted the IETF 19 Trust the right to allow modifications of such material outside the 20 IETF Standards Process. Without obtaining an adequate license from 21 the person(s) controlling the copyright in such materials, this 22 document may not be modified outside the IETF Standards Process, and 23 derivative works of it may not be created outside the IETF Standards 24 Process, except to format it for publication as an RFC or to 25 translate it into languages other than English. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF), its areas, and its working groups. Note that 29 other groups may also distribute working documents as Internet- 30 Drafts. 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 The list of current Internet-Drafts can be accessed at 38 http://www.ietf.org/ietf/1id-abstracts.txt. 40 The list of Internet-Draft Shadow Directories can be accessed at 41 http://www.ietf.org/shadow.html. 43 This Internet-Draft will expire on February 19, 2010. 45 Copyright Notice 47 Copyright (c) 2009 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents in effect on the date of 52 publication of this document (http://trustee.ietf.org/license-info). 53 Please review these documents carefully, as they describe your rights 54 and restrictions with respect to this document. 56 Abstract 58 This specification extends the Web Distributed Authoring and 59 Versioning (WebDAV) MKCOL ("Make Collection") method to allow 60 collections of arbitrary resourcetype to be created and to allow 61 properties to be set at the same time. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 67 3. WebDAV Extended MKCOL . . . . . . . . . . . . . . . . . . . . 4 68 3.1. Extended MKCOL Support . . . . . . . . . . . . . . . . . . 4 69 3.1.1. Example: Using OPTIONS for the Discovery of 70 Support for Extended MKCOL . . . . . . . . . . . . . . 5 71 3.2. Status Codes . . . . . . . . . . . . . . . . . . . . . . . 5 72 3.3. Additional Precondition for Extended MKCOL . . . . . . . . 5 73 3.4. Example: Successful Extended MKCOL Request . . . . . . . . 5 74 3.5. Example: Unsuccessful Extended MKCOL Request . . . . . . . 6 75 4. Using Extended MKCOL as an Alternative for MKxxx Methods . . . 8 76 4.1. MKCALENDAR alternative . . . . . . . . . . . . . . . . . . 8 77 4.1.1. Example: Using MKCOL instead of MKCALENDAR . . . . . . 8 78 5. XML Element Definitions . . . . . . . . . . . . . . . . . . . 10 79 5.1. mkcol XML Element . . . . . . . . . . . . . . . . . . . . 10 80 5.2. mkcol-response XML Element . . . . . . . . . . . . . . . . 10 81 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 82 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 83 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 84 9. Normative References . . . . . . . . . . . . . . . . . . . . . 11 85 Appendix A. Change History (to be removed prior to 86 publication as an RFC) . . . . . . . . . . . . . . . 12 88 1. Introduction 90 WebDAV [RFC4918] defines the HTTP [RFC2616] method MKCOL. This 91 method is used to create WebDAV collections on the server. However, 92 several WebDAV-based specifications (e.g., CalDAV [RFC4791]) define 93 "special" collections - ones which are identified by additional 94 values in the DAV:resourcetype property assigned to the collection 95 resource, or through other means. These "special" collections are 96 created by new methods (e.g., MKCALENDAR). The addition of a new 97 MKxxx method for each new "special" collection adds to server 98 complexity and is detrimental to overall reliability due to the need 99 to make sure intermediaries are aware of these methods. 101 This specification defines an extension to the WebDAV MKCOL method 102 that adds a request body allowing a client to specify WebDAV 103 properties to be set on the newly created collection or resource. In 104 particular, the DAV:resourcetype property can be used to create a 105 "special" collection, or other properties used to create a "special" 106 resource. This avoids the need to invent new MKxxx methods. 108 2. Conventions Used in This Document 110 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 111 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 112 document are to be interpreted as described in [RFC2119]. 114 This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section 115 3.2) as a purely notational convention. WebDAV request and response 116 bodies cannot be validated by a DTD due to the specific extensibility 117 rules defined in Section 17 of [RFC4918] and due to the fact that all 118 XML elements defined by this specification use the XML namespace name 119 "DAV:". In particular: 121 1. element names use the "DAV:" namespace, 123 2. element ordering is irrelevant unless explicitly stated, 125 3. extension elements (elements not already defined as valid child 126 elements) may be added anywhere, except when explicitly stated 127 otherwise, 129 4. extension attributes (attributes not already defined as valid for 130 this element) may be added anywhere, except when explicitly 131 stated otherwise. 133 When an XML element type in the "DAV:" namespace is referenced in 134 this document outside of the context of an XML fragment, the string 135 "DAV:" will be prefixed to the element type. 137 This document inherits, and sometimes extends, DTD productions from 138 Section 14 of [RFC4918]. 140 3. WebDAV Extended MKCOL 142 The WebDAV MKCOL request is extended to allow the inclusion of a 143 request body. The request body is an XML document containing a 144 single DAV:mkcol XML element as the root element. The Content-Type 145 request header MUST be set appropriately for an XML body (e.g., set 146 to "text/xml" or "application/xml"). XML-typed bodies for an MKCOL 147 request that do not have DAV:mkcol as the root element are reserved 148 for future usage. 150 One or more DAV:set XML elements may be included in the DAV:mkcol XML 151 element to allow setting properties on the collection as it is 152 created. In particular, to create a collection of a particular type, 153 the DAV:resourcetype XML element MUST be included in a DAV:set XML 154 element and MUST specify the expected resource type elements for the 155 new resource, that MUST include the DAV:collection element that needs 156 to be present for any WebDAV collection. 158 As per the PROPPATCH method ([RFC4918], Section 9.2), servers MUST 159 process any DAV:set instructions in document order (an exception to 160 the normal rule that ordering is irrelevant). If any one instruction 161 fails to execute successfully, all instructions MUST fail (i.e., 162 either all succeed or all fail). Thus, if any error occurs during 163 processing, all executed instructions MUST be undone and a proper 164 error result returned. Failure to set a property value on the 165 collection MUST result in a failure of the overall MKCOL request - 166 i.e. the collection is not created. 168 The response to an extended MKCOL request MUST be an XML document 169 containing a single DAV:mkcol-response XML element, which MUST 170 contain DAV:propstat XML elements with the status of each property 171 when the request fails due to a failure to set one or more of the 172 properties specified in the request body. The server MAY return a 173 response body in the case where the request is successful, indicating 174 success for setting each property specified in the request body. 175 When an empty response body is returned with a success request status 176 code, the client can assume that all properties were set. 178 In all other respects the behavior of the extended MKCOL request 179 follows that of the standard MKCOL request. 181 3.1. Extended MKCOL Support 183 A server supporting the features described in this document, MUST 184 include "extended-mkcol" as a field in the DAV response header from 185 an OPTIONS request on any URI that supports use of the extended MKCOL 186 method. 188 3.1.1. Example: Using OPTIONS for the Discovery of Support for Extended 189 MKCOL 191 >> Request << 193 OPTIONS /addressbooks/users/ HTTP/1.1 194 Host: addressbook.example.com 196 >> Response << 198 HTTP/1.1 200 OK 199 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE 200 Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL 201 DAV: 1, 2, 3, access-control, extended-mkcol 202 Date: Sat, 11 Nov 2006 09:32:12 GMT 203 Content-Length: 0 205 3.2. Status Codes 207 As per Section 9.3.1 of [RFC4918]. 209 3.3. Additional Precondition for Extended MKCOL 211 WebDAV ([RFC4918], Section 16) defines preconditions and 212 postconditions for request behavior. This specification adds the 213 following precondition for the extended MKCOL request. 215 Name: valid-resourcetype 217 Namespace: DAV: 219 Use with: Typically 403 (Forbidden) 221 Purpose: (precondition) -- The server MUST support the specified 222 resourcetype value for the specified collection. 224 3.4. Example: Successful Extended MKCOL Request 226 This example shows how the extended MKCOL request is used to create a 227 collection of a fictitious type "special-resource". The response 228 body is empty as the request completed successfully. 230 >> Request << 232 MKCOL /home/special/ HTTP/1.1 233 Host: special.example.com 234 Content-Type: application/xml; charset="utf-8" 235 Content-Length: xxxx 237 238 240 241 242 243 244 245 246 Special Resource 247 248 249 251 >> Response << 253 HTTP/1.1 201 Created 254 Cache-Control: no-cache 255 Date: Sat, 11 Nov 2006 09:32:12 GMT 257 3.5. Example: Unsuccessful Extended MKCOL Request 259 This example shows an attempt to use the extended MKCOL request to 260 create a collection of a fictitious type "special-resource", which is 261 not actually supported by the server. The response body shows that 262 an error occurred specifically with the DAV:resourcetype property. 264 >> Request << 266 MKCOL /home/special/ HTTP/1.1 267 Host: special.example.com 268 Content-Type: application/xml; charset="utf-8" 269 Content-Length: xxxx 271 272 274 275 276 277 278 279 280 Special Resource 281 282 283 285 >> Response << 287 HTTP/1.1 403 Forbidden 288 Cache-Control: no-cache 289 Date: Sat, 11 Nov 2006 09:32:12 GMT 290 Content-Type: application/xml; charset="utf-8" 291 Content-Length: xxxx 293 294 295 296 297 298 299 HTTP/1.1 403 Forbidden 300 301 Resource type is not 302 supported by this server 303 304 305 306 307 308 HTTP/1.1 424 Failed Dependency 309 310 312 4. Using Extended MKCOL as an Alternative for MKxxx Methods 314 One of the goals of this extension is to eliminate the need for other 315 extensions to define their own variant of MKCOL to create the special 316 collections they need. This extension can be used as an alternative 317 to existing MKxxx methods in other extensions as detailed below. If 318 a server supports this extension and the other extension listed, then 319 the server MUST support use of the extended MKCOL method to achieve 320 the same result as the MKxxx method of the other extension. 322 4.1. MKCALENDAR alternative 324 CalDAV defines the MKCALENDAR method to create a calendar collection 325 as well as set properties during creation ([RFC4791], Section 5.3.1). 327 The extended MKCOL method can be used instead by specifying both DAV: 328 collection and CALDAV:calendar-collection XML elements in the DAV: 329 resourcetype property, set during the extended MKCOL request. 331 4.1.1. Example: Using MKCOL instead of MKCALENDAR 333 The first example below shows an MKCALENDAR request containing a 334 CALDAV:mkcalendar XML element in the request body, and returning a 335 CALDAV:mkcalendar-response XML element in the response body. 337 >> MKCALENDAR Request << 339 MKCALENDAR /home/lisa/calendars/events/ HTTP/1.1 340 Host: calendar.example.com 341 Content-Type: application/xml; charset="utf-8" 342 Content-Length: xxxx 344 345 347 348 349 Lisa's Events 350 351 352 353 >> MKCALENDAR Response << 355 HTTP/1.1 201 Created 356 Cache-Control: no-cache 357 Date: Sat, 11 Nov 2006 09:32:12 GMT 358 Content-Type: application/xml; charset="utf-8" 359 Content-Length: xxxx 361 362 364 365 366 367 368 HTTP/1.1 200 OK 369 370 372 The second example shows the equivalent extended MKCOL request with 373 the same request and response XML elements. 375 >> MKCOL Request << 377 MKCOL /home/lisa/calendars/events/ HTTP/1.1 378 Host: calendar.example.com 379 Content-Type: application/xml; charset="utf-8" 380 Content-Length: xxxx 382 383 385 386 387 388 389 390 391 Lisa's Events 392 393 394 395 >> MKCOL Response << 397 HTTP/1.1 201 Created 398 Cache-Control: no-cache 399 Date: Sat, 11 Nov 2006 09:32:12 GMT 400 Content-Type: application/xml; charset="utf-8" 401 Content-Length: xxxx 403 404 406 407 408 409 410 411 HTTP/1.1 200 OK 412 413 415 5. XML Element Definitions 417 5.1. mkcol XML Element 419 Name: mkcol 421 Namespace: DAV: 423 Purpose: Used in a request to specify properties to be set in an 424 extended MKCOL request, as well as any additional information 425 needed when creating the resource. 427 Description: This XML element is a container for the information 428 required to modify the properties on a collection resource as it 429 is created in an extended MKCOL request. 431 Definition: 433 435 5.2. mkcol-response XML Element 437 Name: mkcol-response 439 Namespace: DAV: 441 Purpose: Used in a response to indicate the status of properties 442 that were set or failed to be set during an extended MKCOL 443 request. 445 Description: This XML element is a container for the information 446 returned about a resource that has been created in an extended 447 MKCOL request. 449 Definition: 451 453 6. Security Considerations 455 This extension does not introduce any new security concerns beyond 456 those already described in HTTP and WebDAV. 458 7. IANA Considerations 460 This document does not require any actions on the part of IANA. 462 8. Acknowledgments 464 Thanks to Bernard Desruisseaux, Mike Douglass, Alexey Melnikov, 465 Julian Reschke, and Simon Vaillancourt. 467 9. Normative References 469 [RFC2119] Bradner, S., "Key words for use in RFCs to 470 Indicate Requirement Levels", BCP 14, 471 RFC 2119, March 1997. 473 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, 474 H., Masinter, L., Leach, P., and T. Berners- 475 Lee, "Hypertext Transfer Protocol -- 476 HTTP/1.1", RFC 2616, June 1999. 478 [RFC4791] Daboo, C., Desruisseaux, B., and L. 479 Dusseault, "Calendaring Extensions to WebDAV 480 (CalDAV)", RFC 4791, March 2007. 482 [RFC4918] Dusseault, L., "HTTP Extensions for Web 483 Distributed Authoring and Versioning 484 (WebDAV)", RFC 4918, June 2007. 486 [W3C.REC-xml-20081126] Paoli, J., Yergeau, F., Bray, T., Sperberg- 487 McQueen, C., and E. Maler, "Extensible Markup 488 Language (XML) 1.0 (Fifth Edition)", World 489 Wide Web Consortium Recommendation REC-xml- 490 20081126, November 2008, 491 . 493 Appendix A. Change History (to be removed prior to publication as an 494 RFC) 496 Changes in -06: 498 1. Fixed section title. 500 2. Gen-ART review comments addressed. 502 3. Added "Updates 4791, 4918". 504 4. Tweaked examples. 506 Changes in -05: 508 1. Make response body optional in case of complete success. 510 2. Added an example of an error with extended MKCOL. 512 Changes in -04: 514 1. WGLC: minor wording tweaks. 516 2. WGLC: switch to using XML conventions text from RFC5323. 518 3. WGLC: MAY -> may in section 3/paragraph 2. 520 4. WGLC: mkcol-response DTD - removed ANY. 522 5. WGLC: updated to W3C.REC-xml-20081126 reference. 524 Changes in -03: 526 1. Boiler plate update. 528 Changes in -02: 530 1. Minor formatting/wording changes proposed by Julian Reschke were 531 applied. 533 2. Removed reference to DeltaV entirely as the spec no longer 534 replaces the MKxxx DeltaV defines. 536 3. Added Namespace definition to precondition. 538 4. Added reference to 4918 XML extensibility rules. 540 5. Added statement that DAV:collection must be present in DAV: 541 resourcetype in the request. 543 6. Added statement on use of DTD fragments. 545 7. Added statement about setting proper Content-Type for the MKCOL 546 body. 548 8. Added statement that MKCOL bodies using a different root element 549 are reserved for future extensions. 551 Changes in -01: 553 1. Fixed an example. 555 Changes in -00: 557 1. Removed MKACTIVITY and MKWORKSPACE replacement behavior. 559 2. Added valid-resourcetype precondition. 561 Author's Address 563 Cyrus Daboo 564 Apple Inc. 565 1 Infinite Loop 566 Cupertino, CA 95014 567 USA 569 EMail: cyrus@daboo.name 570 URI: http://www.apple.com/