idnits 2.17.1 draft-ietf-vcarddav-webdav-mkcol-05.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 : ---------------------------------------------------------------------------- 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 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 (July 13, 2009) is 5398 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 (==), 2 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 Intended status: Standards Track July 13, 2009 5 Expires: January 14, 2010 7 Extended MKCOL for WebDAV 8 draft-ietf-vcarddav-webdav-mkcol-05 10 Status of This Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. This document may contain material 14 from IETF Documents or IETF Contributions published or made publicly 15 available before November 10, 2008. The person(s) controlling the 16 copyright in some of this material may not have granted the IETF 17 Trust the right to allow modifications of such material outside the 18 IETF Standards Process. Without obtaining an adequate license from 19 the person(s) controlling the copyright in such materials, this 20 document may not be modified outside the IETF Standards Process, and 21 derivative works of it may not be created outside the IETF Standards 22 Process, except to format it for publication as an RFC or to 23 translate it into languages other than English. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF), its areas, and its working groups. Note that 27 other groups may also distribute working documents as Internet- 28 Drafts. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 The list of current Internet-Drafts can be accessed at 36 http://www.ietf.org/ietf/1id-abstracts.txt. 38 The list of Internet-Draft Shadow Directories can be accessed at 39 http://www.ietf.org/shadow.html. 41 This Internet-Draft will expire on January 14, 2010. 43 Copyright Notice 45 Copyright (c) 2009 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents in effect on the date of 50 publication of this document (http://trustee.ietf.org/license-info). 51 Please review these documents carefully, as they describe your rights 52 and restrictions with respect to this document. 54 Abstract 56 This specification extends the Web Distributed Authoring and 57 Versioning (WebDAV) MKCOL method to allow collections of arbitrary 58 resourcetype to be created and to allow properties to be set at the 59 same time. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 65 3. WebDAV extended MKCOL . . . . . . . . . . . . . . . . . . . . 4 66 3.1. Extended MKCOL Support . . . . . . . . . . . . . . . . . . 4 67 3.1.1. Example: Using OPTIONS for the Discovery of 68 Support for Extended MKCOL . . . . . . . . . . . . . . 5 69 3.2. Status Codes . . . . . . . . . . . . . . . . . . . . . . . 5 70 3.3. Additional Precondition for Extended MKCOL . . . . . . . . 5 71 3.4. Example: Successful Extended MKCOL Request . . . . . . . . 5 72 3.5. Example: Successful Extended MKCOL Request . . . . . . . . 6 73 4. Replacing Existing MKxxx Methods . . . . . . . . . . . . . . . 8 74 4.1. MKCALENDAR Replacement . . . . . . . . . . . . . . . . . . 8 75 4.1.1. Example: Replacing MKCALENDAR with MKCOL . . . . . . . 8 76 5. XML Element Definitions . . . . . . . . . . . . . . . . . . . 10 77 5.1. mkcol XML Element . . . . . . . . . . . . . . . . . . . . 10 78 5.2. mkcol-response XML Element . . . . . . . . . . . . . . . . 10 79 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 80 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 81 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 82 9. Normative References . . . . . . . . . . . . . . . . . . . . . 11 83 Appendix A. Change History (to be removed prior to 84 publication as an RFC) . . . . . . . . . . . . . . . 12 86 1. Introduction 88 WebDAV [RFC4918] defines the HTTP [RFC2616] method MKCOL. This 89 method is used to create WebDAV collections on the server. However, 90 several WebDAV-based specifications (e.g., CalDAV [RFC4791]) define 91 "special" collections - ones which are identified by additional 92 values in the DAV:resourcetype property assigned to the collection 93 resource, or through other means. These "special" collections are 94 created by new methods (e.g., MKCALENDAR). The addition of a new 95 MKxxx method for each new "special" collection adds to server 96 complexity and is detrimental to overall reliability due to the need 97 to make sure intermediaries are aware of these methods. 99 This specification defines an extension to the WebDAV MKCOL method 100 that adds a request body allowing a client to specify WebDAV 101 properties to be set on the newly created collection or resource. In 102 particular, the DAV:resourcetype property can be used to create a 103 "special" collection, or other properties used to create a "special" 104 resource. This avoids the need to invent new MKxxx methods. 106 2. Conventions Used in This Document 108 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 109 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 110 document are to be interpreted as described in [RFC2119]. 112 This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section 113 3.2) as a purely notational convention. WebDAV request and response 114 bodies cannot be validated by a DTD due to the specific extensibility 115 rules defined in Section 17 of [RFC4918] and due to the fact that all 116 XML elements defined by this specification use the XML namespace name 117 "DAV:". In particular: 119 1. element names use the "DAV:" namespace, 121 2. element ordering is irrelevant unless explicitly stated, 123 3. extension elements (elements not already defined as valid child 124 elements) may be added anywhere, except when explicitly stated 125 otherwise, 127 4. extension attributes (attributes not already defined as valid for 128 this element) may be added anywhere, except when explicitly 129 stated otherwise. 131 When an XML element type in the "DAV:" namespace is referenced in 132 this document outside of the context of an XML fragment, the string 133 "DAV:" will be prefixed to the element type. 135 This document inherits, and sometimes extends, DTD productions from 136 Section 14 of [RFC4918]. 138 3. WebDAV extended MKCOL 140 The WebDAV MKCOL request is extended to allow the inclusion of a 141 request body. The request body is an XML document containing a 142 single DAV:mkcol XML element as the root element. The Content-Type 143 request header MUST be set appropriately for an XML body (e.g., set 144 to "text/xml" or "application/xml"). XML-typed bodies for an MKCOL 145 request that do not have DAV:mkcol as the root element are reserved 146 for future usage. 148 One or more DAV:set XML elements may be included in the DAV:mkcol XML 149 element to allow setting properties on the collection as it is 150 created. In particular, to create a collection of a particular type, 151 the DAV:resourcetype XML element MUST be included in a DAV:set XML 152 element and MUST specify the expected resource type elements for the 153 new resource, that MUST include the DAV:collection element that needs 154 to be present for any WebDAV collection. 156 As per the PROPPATCH method ([RFC4918], Section 9.2), servers MUST 157 process any DAV:set instructions in document order (an exception to 158 the normal rule that ordering is irrelevant). Instructions MUST 159 either all be executed or none executed. Thus, if any error occurs 160 during processing, all executed instructions MUST be undone and a 161 proper error result returned. Failure to set a property value on the 162 collection MUST result in a failure of the overall MKCOL request - 163 i.e. the collection is not created. 165 The response to an extended MKCOL request MUST be an XML document 166 containing a single DAV:mkcol-response XML element, which MUST 167 contain DAV:propstat XML elements with the status of each property 168 when the request fails due to a failure to set one or more of the 169 properties specified in the request body. The server MAY return a 170 response body in the case where the request is successful, indicating 171 success for setting each property specified in the request body. 172 When an empty response body is returned with a success request status 173 code, the client can assume that all properties were set. 175 In all other respects the behavior of the extended MKCOL request 176 follows that of the standard MKCOL request. 178 3.1. Extended MKCOL Support 180 A server supporting the features described in this document, MUST 181 include "extended-mkcol" as a field in the DAV response header from 182 an OPTIONS request on any URI that supports use of the extended MKCOL 183 method. 185 3.1.1. Example: Using OPTIONS for the Discovery of Support for Extended 186 MKCOL 188 >> Request << 190 OPTIONS /addressbooks/users/ HTTP/1.1 191 Host: addressbook.example.com 193 >> Response << 195 HTTP/1.1 200 OK 196 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE 197 Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL 198 DAV: 1, 2, 3, access-control, extended-mkcol 199 Date: Sat, 11 Nov 2006 09:32:12 GMT 200 Content-Length: 0 202 3.2. Status Codes 204 As per Section 9.3.1 of [RFC4918]. 206 3.3. Additional Precondition for Extended MKCOL 208 WebDAV ([RFC4918], Section 16) defines preconditions and 209 postconditions for request behavior. This specification adds the 210 following precondition for the extended MKCOL request. 212 Name: valid-resourcetype 214 Namespace: DAV: 216 Use with: Typically 403 (Forbidden) 218 Purpose: (precondition) -- The server MUST support the specified 219 resourcetype value for the specified collection. 221 3.4. Example: Successful Extended MKCOL Request 223 This example shows how the extended MKCOL request is used to create a 224 collection of a fictitious type "special-resource". The response 225 body is empty as the request completed successfully. 227 >> Request << 229 MKCOL /home/special/ HTTP/1.1 230 Host: special.example.com 231 Content-Type: application/xml; charset="utf-8" 232 Content-Length: xxxx 234 235 237 238 239 240 241 242 243 Special Resource 244 245 246 248 >> Response << 250 HTTP/1.1 201 Created 251 Cache-Control: no-cache 252 Date: Sat, 11 Nov 2006 09:32:12 GMT 254 3.5. Example: Successful Extended MKCOL Request 256 This example shows an attempt to use the extended MKCOL request to 257 create a collection of a fictitious type "special-resource", which is 258 not actually supported by the server. The response body shows that 259 an error occurred specifically with the DAV:resourcetype property. 261 >> Request << 263 MKCOL /home/special/ HTTP/1.1 264 Host: special.example.com 265 Content-Type: application/xml; charset="utf-8" 266 Content-Length: xxxx 268 269 271 272 273 274 275 276 277 Special Resource 278 279 280 282 >> Response << 284 HTTP/1.1 403 Forbidden 285 Cache-Control: no-cache 286 Date: Sat, 11 Nov 2006 09:32:12 GMT 287 Content-Type: application/xml; charset="utf-8" 288 Content-Length: xxxx 290 291 292 293 294 295 296 HTTP/1.1 403 Forbidden 297 298 Resource type is not 299 supported by this server 300 301 302 303 304 305 HTTP/1.1 424 Failed Dependency 306 307 309 4. Replacing Existing MKxxx Methods 311 One of the goals of this extension is to eliminate the need for other 312 extensions to define their own variant of MKCOL to create the special 313 collections they need. This extension can be used to replace 314 existing MKxxx methods in other extensions as detailed below. If a 315 server supports this extension and the other extension listed, then 316 the server MUST support use of the extended MKCOL method to achieve 317 the same result as the MKxxx method of the other extension. 319 4.1. MKCALENDAR Replacement 321 CalDAV defines the MKCALENDAR method to create a calendar collection 322 as well as set properties during creation ([RFC4791], Section 5.3.1). 324 The extended MKCOL method can be used instead by specifying both DAV: 325 collection and CALDAV:calendar-collection XML elements in the DAV: 326 resourcetype property, set during the extended MKCOL request. 328 4.1.1. Example: Replacing MKCALENDAR with MKCOL 330 The first example below shows an MKCALENDAR request containing a 331 CALDAV:mkcalendar XML element in the request body, and returning a 332 CALDAV:mkcalendar-response XML element in the response body. 334 >> MKCALENDAR Request << 336 MKCALENDAR /home/lisa/calendars/events/ HTTP/1.1 337 Host: calendar.example.com 338 Content-Type: application/xml; charset="utf-8" 339 Content-Length: xxxx 341 342 344 345 346 Lisa's Events 347 348 349 350 >> MKCALENDAR Response << 352 HTTP/1.1 201 Created 353 Cache-Control: no-cache 354 Date: Sat, 11 Nov 2006 09:32:12 GMT 355 Content-Type: application/xml; charset="utf-8" 356 Content-Length: xxxx 358 359 361 362 363 364 365 HTTP/1.1 200 OK 366 367 369 The second example shows the equivalent extended MKCOL request with 370 the same request and response XML elements. 372 >> MKCOL Request << 374 MKCOL /home/cyrus/calendars/events/ HTTP/1.1 375 Host: calendar.example.com 376 Content-Type: application/xml; charset="utf-8" 377 Content-Length: xxxx 379 380 382 383 384 385 386 387 388 Cyrus' Events 389 390 391 392 >> MKCOL Response << 394 HTTP/1.1 201 Created 395 Cache-Control: no-cache 396 Date: Sat, 11 Nov 2006 09:32:12 GMT 397 Content-Type: application/xml; charset="utf-8" 398 Content-Length: xxxx 400 401 403 404 405 406 407 408 HTTP/1.1 200 OK 409 410 412 5. XML Element Definitions 414 5.1. mkcol XML Element 416 Name: mkcol 418 Namespace: DAV: 420 Purpose: Used in a request to specify properties to be set in an 421 extended MKCOL request, as well as any additional information 422 needed when creating the resource. 424 Description: This XML element is a container for the information 425 required to modify the properties on a collection resource as it 426 is created in an extended MKCOL request. 428 Definition: 430 432 5.2. mkcol-response XML Element 434 Name: mkcol-response 436 Namespace: DAV: 438 Purpose: Used in a response to indicate the status of properties 439 that were set or failed to be set during an extended MKCOL 440 request. 442 Description: This XML element is a container for the information 443 returned about a resource that has been created in an extended 444 MKCOL request. 446 Definition: 448 450 6. Security Considerations 452 This extension does not introduce any new security concerns beyond 453 those already described in HTTP and WebDAV. 455 7. IANA Considerations 457 This document does not require any actions on the part of IANA. 459 8. Acknowledgments 461 Thanks to Bernard Desruisseaux, Mike Douglass, Julian Reschke, and 462 Simon Vaillancourt. 464 9. Normative References 466 [RFC2119] Bradner, S., "Key words for use in RFCs to 467 Indicate Requirement Levels", BCP 14, 468 RFC 2119, March 1997. 470 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, 471 H., Masinter, L., Leach, P., and T. Berners- 472 Lee, "Hypertext Transfer Protocol -- 473 HTTP/1.1", RFC 2616, June 1999. 475 [RFC4791] Daboo, C., Desruisseaux, B., and L. 476 Dusseault, "Calendaring Extensions to WebDAV 477 (CalDAV)", RFC 4791, March 2007. 479 [RFC4918] Dusseault, L., "HTTP Extensions for Web 480 Distributed Authoring and Versioning 481 (WebDAV)", RFC 4918, June 2007. 483 [W3C.REC-xml-20081126] Paoli, J., Yergeau, F., Bray, T., Sperberg- 484 McQueen, C., and E. Maler, "Extensible Markup 485 Language (XML) 1.0 (Fifth Edition)", World 486 Wide Web Consortium Recommendation REC-xml- 487 20081126, November 2008, 488 . 490 Appendix A. Change History (to be removed prior to publication as an 491 RFC) 493 Changes in -05: 495 1. Make response body optional in case of complete success. 497 2. Added an example of an error with extended MKCOL. 499 Changes in -04: 501 1. WGLC: minor wording tweaks. 503 2. WGLC: switch to using XML conventions text from RFC5323. 505 3. WGLC: MAY -> may in section 3/paragraph 2. 507 4. WGLC: mkcol-response DTD - removed ANY. 509 5. WGLC: updated to W3C.REC-xml-20081126 reference. 511 Changes in -03: 513 1. Boiler plate update. 515 Changes in -02: 517 1. Minor formatting/wording changes proposed by Julian Reschke were 518 applied. 520 2. Removed reference to DeltaV entirely as the spec no longer 521 replaces the MKxxx DeltaV defines. 523 3. Added Namespace definition to precondition. 525 4. Added reference to 4918 XML extensibility rules. 527 5. Added statement that DAV:collection must be present in DAV: 528 resourcetype in the request. 530 6. Added statement on use of DTD fragments. 532 7. Added statement about setting proper Content-Type for the MKCOL 533 body. 535 8. Added statement that MKCOL bodies using a different root element 536 are reserved for future extensions. 538 Changes in -01: 540 1. Fixed an example. 542 Changes in -00: 544 1. Removed MKACTIVITY and MKWORKSPACE replacement behavior. 546 2. Added valid-resourcetype precondition. 548 Author's Address 550 Cyrus Daboo 551 Apple Inc. 552 1 Infinite Loop 553 Cupertino, CA 95014 554 USA 556 EMail: cyrus@daboo.name 557 URI: http://www.apple.com/