draft-ietf-vcarddav-webdav-mkcol-05.txt   draft-ietf-vcarddav-webdav-mkcol-06.txt 
Network Working Group C. Daboo Network Working Group C. Daboo
Internet-Draft Apple Inc. Internet-Draft Apple Inc.
Intended status: Standards Track July 13, 2009 Updates: 4791, 4918 August 18, 2009
Expires: January 14, 2010 (if approved)
Intended status: Standards Track
Expires: February 19, 2010
Extended MKCOL for WebDAV Extended MKCOL for WebDAV
draft-ietf-vcarddav-webdav-mkcol-05 draft-ietf-vcarddav-webdav-mkcol-06
Status of This Memo Status of This Memo
This Internet-Draft is submitted to IETF in full conformance with the This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79. This document may contain material provisions of BCP 78 and BCP 79. This document may contain material
from IETF Documents or IETF Contributions published or made publicly from IETF Documents or IETF Contributions published or made publicly
available before November 10, 2008. The person(s) controlling the available before November 10, 2008. The person(s) controlling the
copyright in some of this material may not have granted the IETF copyright in some of this material may not have granted the IETF
Trust the right to allow modifications of such material outside the Trust the right to allow modifications of such material outside the
IETF Standards Process. Without obtaining an adequate license from IETF Standards Process. Without obtaining an adequate license from
skipping to change at page 1, line 42 skipping to change at page 1, line 44
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on January 14, 2010. This Internet-Draft will expire on February 19, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents in effect on the date of Provisions Relating to IETF Documents in effect on the date of
publication of this document (http://trustee.ietf.org/license-info). publication of this document (http://trustee.ietf.org/license-info).
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. and restrictions with respect to this document.
Abstract Abstract
This specification extends the Web Distributed Authoring and This specification extends the Web Distributed Authoring and
Versioning (WebDAV) MKCOL method to allow collections of arbitrary Versioning (WebDAV) MKCOL ("Make Collection") method to allow
resourcetype to be created and to allow properties to be set at the collections of arbitrary resourcetype to be created and to allow
same time. properties to be set at the same time.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions Used in This Document . . . . . . . . . . . . . . 3 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
3. WebDAV extended MKCOL . . . . . . . . . . . . . . . . . . . . 4 3. WebDAV Extended MKCOL . . . . . . . . . . . . . . . . . . . . 4
3.1. Extended MKCOL Support . . . . . . . . . . . . . . . . . . 4 3.1. Extended MKCOL Support . . . . . . . . . . . . . . . . . . 4
3.1.1. Example: Using OPTIONS for the Discovery of 3.1.1. Example: Using OPTIONS for the Discovery of
Support for Extended MKCOL . . . . . . . . . . . . . . 5 Support for Extended MKCOL . . . . . . . . . . . . . . 5
3.2. Status Codes . . . . . . . . . . . . . . . . . . . . . . . 5 3.2. Status Codes . . . . . . . . . . . . . . . . . . . . . . . 5
3.3. Additional Precondition for Extended MKCOL . . . . . . . . 5 3.3. Additional Precondition for Extended MKCOL . . . . . . . . 5
3.4. Example: Successful Extended MKCOL Request . . . . . . . . 5 3.4. Example: Successful Extended MKCOL Request . . . . . . . . 5
3.5. Example: Successful Extended MKCOL Request . . . . . . . . 6 3.5. Example: Unsuccessful Extended MKCOL Request . . . . . . . 6
4. Replacing Existing MKxxx Methods . . . . . . . . . . . . . . . 8 4. Using Extended MKCOL as an Alternative for MKxxx Methods . . . 8
4.1. MKCALENDAR Replacement . . . . . . . . . . . . . . . . . . 8 4.1. MKCALENDAR alternative . . . . . . . . . . . . . . . . . . 8
4.1.1. Example: Replacing MKCALENDAR with MKCOL . . . . . . . 8 4.1.1. Example: Using MKCOL instead of MKCALENDAR . . . . . . 8
5. XML Element Definitions . . . . . . . . . . . . . . . . . . . 10 5. XML Element Definitions . . . . . . . . . . . . . . . . . . . 10
5.1. mkcol XML Element . . . . . . . . . . . . . . . . . . . . 10 5.1. mkcol XML Element . . . . . . . . . . . . . . . . . . . . 10
5.2. mkcol-response XML Element . . . . . . . . . . . . . . . . 10 5.2. mkcol-response XML Element . . . . . . . . . . . . . . . . 10
6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11
9. Normative References . . . . . . . . . . . . . . . . . . . . . 11 9. Normative References . . . . . . . . . . . . . . . . . . . . . 11
Appendix A. Change History (to be removed prior to Appendix A. Change History (to be removed prior to
publication as an RFC) . . . . . . . . . . . . . . . 12 publication as an RFC) . . . . . . . . . . . . . . . 12
skipping to change at page 4, line 8 skipping to change at page 4, line 8
this element) may be added anywhere, except when explicitly this element) may be added anywhere, except when explicitly
stated otherwise. stated otherwise.
When an XML element type in the "DAV:" namespace is referenced in When an XML element type in the "DAV:" namespace is referenced in
this document outside of the context of an XML fragment, the string this document outside of the context of an XML fragment, the string
"DAV:" will be prefixed to the element type. "DAV:" will be prefixed to the element type.
This document inherits, and sometimes extends, DTD productions from This document inherits, and sometimes extends, DTD productions from
Section 14 of [RFC4918]. Section 14 of [RFC4918].
3. WebDAV extended MKCOL 3. WebDAV Extended MKCOL
The WebDAV MKCOL request is extended to allow the inclusion of a The WebDAV MKCOL request is extended to allow the inclusion of a
request body. The request body is an XML document containing a request body. The request body is an XML document containing a
single DAV:mkcol XML element as the root element. The Content-Type single DAV:mkcol XML element as the root element. The Content-Type
request header MUST be set appropriately for an XML body (e.g., set request header MUST be set appropriately for an XML body (e.g., set
to "text/xml" or "application/xml"). XML-typed bodies for an MKCOL to "text/xml" or "application/xml"). XML-typed bodies for an MKCOL
request that do not have DAV:mkcol as the root element are reserved request that do not have DAV:mkcol as the root element are reserved
for future usage. for future usage.
One or more DAV:set XML elements may be included in the DAV:mkcol XML One or more DAV:set XML elements may be included in the DAV:mkcol XML
element to allow setting properties on the collection as it is element to allow setting properties on the collection as it is
created. In particular, to create a collection of a particular type, created. In particular, to create a collection of a particular type,
the DAV:resourcetype XML element MUST be included in a DAV:set XML the DAV:resourcetype XML element MUST be included in a DAV:set XML
element and MUST specify the expected resource type elements for the element and MUST specify the expected resource type elements for the
new resource, that MUST include the DAV:collection element that needs new resource, that MUST include the DAV:collection element that needs
to be present for any WebDAV collection. to be present for any WebDAV collection.
As per the PROPPATCH method ([RFC4918], Section 9.2), servers MUST As per the PROPPATCH method ([RFC4918], Section 9.2), servers MUST
process any DAV:set instructions in document order (an exception to process any DAV:set instructions in document order (an exception to
the normal rule that ordering is irrelevant). Instructions MUST the normal rule that ordering is irrelevant). If any one instruction
either all be executed or none executed. Thus, if any error occurs fails to execute successfully, all instructions MUST fail (i.e.,
during processing, all executed instructions MUST be undone and a either all succeed or all fail). Thus, if any error occurs during
proper error result returned. Failure to set a property value on the processing, all executed instructions MUST be undone and a proper
error result returned. Failure to set a property value on the
collection MUST result in a failure of the overall MKCOL request - collection MUST result in a failure of the overall MKCOL request -
i.e. the collection is not created. i.e. the collection is not created.
The response to an extended MKCOL request MUST be an XML document The response to an extended MKCOL request MUST be an XML document
containing a single DAV:mkcol-response XML element, which MUST containing a single DAV:mkcol-response XML element, which MUST
contain DAV:propstat XML elements with the status of each property contain DAV:propstat XML elements with the status of each property
when the request fails due to a failure to set one or more of the when the request fails due to a failure to set one or more of the
properties specified in the request body. The server MAY return a properties specified in the request body. The server MAY return a
response body in the case where the request is successful, indicating response body in the case where the request is successful, indicating
success for setting each property specified in the request body. success for setting each property specified in the request body.
skipping to change at page 6, line 32 skipping to change at page 6, line 32
</D:prop> </D:prop>
</D:set> </D:set>
</D:mkcol> </D:mkcol>
>> Response << >> Response <<
HTTP/1.1 201 Created HTTP/1.1 201 Created
Cache-Control: no-cache Cache-Control: no-cache
Date: Sat, 11 Nov 2006 09:32:12 GMT Date: Sat, 11 Nov 2006 09:32:12 GMT
3.5. Example: Successful Extended MKCOL Request 3.5. Example: Unsuccessful Extended MKCOL Request
This example shows an attempt to use the extended MKCOL request to This example shows an attempt to use the extended MKCOL request to
create a collection of a fictitious type "special-resource", which is create a collection of a fictitious type "special-resource", which is
not actually supported by the server. The response body shows that not actually supported by the server. The response body shows that
an error occurred specifically with the DAV:resourcetype property. an error occurred specifically with the DAV:resourcetype property.
>> Request << >> Request <<
MKCOL /home/special/ HTTP/1.1 MKCOL /home/special/ HTTP/1.1
Host: special.example.com Host: special.example.com
skipping to change at page 8, line 5 skipping to change at page 8, line 5
supported by this server</D:responsedescription> supported by this server</D:responsedescription>
</D:propstat> </D:propstat>
<D:propstat> <D:propstat>
<D:prop> <D:prop>
<D:displayname/> <D:displayname/>
</D:prop> </D:prop>
<D:status>HTTP/1.1 424 Failed Dependency</D:status> <D:status>HTTP/1.1 424 Failed Dependency</D:status>
</D:propstat> </D:propstat>
</D:mkcol-response> </D:mkcol-response>
4. Replacing Existing MKxxx Methods 4. Using Extended MKCOL as an Alternative for MKxxx Methods
One of the goals of this extension is to eliminate the need for other One of the goals of this extension is to eliminate the need for other
extensions to define their own variant of MKCOL to create the special extensions to define their own variant of MKCOL to create the special
collections they need. This extension can be used to replace collections they need. This extension can be used as an alternative
existing MKxxx methods in other extensions as detailed below. If a to existing MKxxx methods in other extensions as detailed below. If
server supports this extension and the other extension listed, then a server supports this extension and the other extension listed, then
the server MUST support use of the extended MKCOL method to achieve the server MUST support use of the extended MKCOL method to achieve
the same result as the MKxxx method of the other extension. the same result as the MKxxx method of the other extension.
4.1. MKCALENDAR Replacement 4.1. MKCALENDAR alternative
CalDAV defines the MKCALENDAR method to create a calendar collection CalDAV defines the MKCALENDAR method to create a calendar collection
as well as set properties during creation ([RFC4791], Section 5.3.1). as well as set properties during creation ([RFC4791], Section 5.3.1).
The extended MKCOL method can be used instead by specifying both DAV: The extended MKCOL method can be used instead by specifying both DAV:
collection and CALDAV:calendar-collection XML elements in the DAV: collection and CALDAV:calendar-collection XML elements in the DAV:
resourcetype property, set during the extended MKCOL request. resourcetype property, set during the extended MKCOL request.
4.1.1. Example: Replacing MKCALENDAR with MKCOL 4.1.1. Example: Using MKCOL instead of MKCALENDAR
The first example below shows an MKCALENDAR request containing a The first example below shows an MKCALENDAR request containing a
CALDAV:mkcalendar XML element in the request body, and returning a CALDAV:mkcalendar XML element in the request body, and returning a
CALDAV:mkcalendar-response XML element in the response body. CALDAV:mkcalendar-response XML element in the response body.
>> MKCALENDAR Request << >> MKCALENDAR Request <<
MKCALENDAR /home/lisa/calendars/events/ HTTP/1.1 MKCALENDAR /home/lisa/calendars/events/ HTTP/1.1
Host: calendar.example.com Host: calendar.example.com
Content-Type: application/xml; charset="utf-8" Content-Type: application/xml; charset="utf-8"
skipping to change at page 9, line 28 skipping to change at page 9, line 28
</D:prop> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status> <D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:propstat>
</C:mkcalendar-response> </C:mkcalendar-response>
The second example shows the equivalent extended MKCOL request with The second example shows the equivalent extended MKCOL request with
the same request and response XML elements. the same request and response XML elements.
>> MKCOL Request << >> MKCOL Request <<
MKCOL /home/cyrus/calendars/events/ HTTP/1.1 MKCOL /home/lisa/calendars/events/ HTTP/1.1
Host: calendar.example.com Host: calendar.example.com
Content-Type: application/xml; charset="utf-8" Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?> <?xml version="1.0" encoding="utf-8" ?>
<D:mkcol xmlns:D="DAV:" <D:mkcol xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav"> xmlns:C="urn:ietf:params:xml:ns:caldav">
<D:set> <D:set>
<D:prop> <D:prop>
<D:resourcetype> <D:resourcetype>
<D:collection/> <D:collection/>
<C:calendar/> <C:calendar/>
</D:resourcetype> </D:resourcetype>
<D:displayname>Cyrus' Events</D:displayname> <D:displayname>Lisa's Events</D:displayname>
</D:prop> </D:prop>
</D:set> </D:set>
</D:mkcol> </D:mkcol>
>> MKCOL Response << >> MKCOL Response <<
HTTP/1.1 201 Created HTTP/1.1 201 Created
Cache-Control: no-cache Cache-Control: no-cache
Date: Sat, 11 Nov 2006 09:32:12 GMT Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: application/xml; charset="utf-8" Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx Content-Length: xxxx
skipping to change at page 11, line 28 skipping to change at page 11, line 28
This extension does not introduce any new security concerns beyond This extension does not introduce any new security concerns beyond
those already described in HTTP and WebDAV. those already described in HTTP and WebDAV.
7. IANA Considerations 7. IANA Considerations
This document does not require any actions on the part of IANA. This document does not require any actions on the part of IANA.
8. Acknowledgments 8. Acknowledgments
Thanks to Bernard Desruisseaux, Mike Douglass, Julian Reschke, and Thanks to Bernard Desruisseaux, Mike Douglass, Alexey Melnikov,
Simon Vaillancourt. Julian Reschke, and Simon Vaillancourt.
9. Normative References 9. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to [RFC2119] Bradner, S., "Key words for use in RFCs to
Indicate Requirement Levels", BCP 14, Indicate Requirement Levels", BCP 14,
RFC 2119, March 1997. RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk,
H., Masinter, L., Leach, P., and T. Berners- H., Masinter, L., Leach, P., and T. Berners-
Lee, "Hypertext Transfer Protocol -- Lee, "Hypertext Transfer Protocol --
skipping to change at page 12, line 11 skipping to change at page 12, line 11
[W3C.REC-xml-20081126] Paoli, J., Yergeau, F., Bray, T., Sperberg- [W3C.REC-xml-20081126] Paoli, J., Yergeau, F., Bray, T., Sperberg-
McQueen, C., and E. Maler, "Extensible Markup McQueen, C., and E. Maler, "Extensible Markup
Language (XML) 1.0 (Fifth Edition)", World Language (XML) 1.0 (Fifth Edition)", World
Wide Web Consortium Recommendation REC-xml- Wide Web Consortium Recommendation REC-xml-
20081126, November 2008, 20081126, November 2008,
<http://www.w3.org/TR/2008/REC-xml-20081126>. <http://www.w3.org/TR/2008/REC-xml-20081126>.
Appendix A. Change History (to be removed prior to publication as an Appendix A. Change History (to be removed prior to publication as an
RFC) RFC)
Changes in -06:
1. Fixed section title.
2. Gen-ART review comments addressed.
3. Added "Updates 4791, 4918".
4. Tweaked examples.
Changes in -05: Changes in -05:
1. Make response body optional in case of complete success. 1. Make response body optional in case of complete success.
2. Added an example of an error with extended MKCOL. 2. Added an example of an error with extended MKCOL.
Changes in -04: Changes in -04:
1. WGLC: minor wording tweaks. 1. WGLC: minor wording tweaks.
 End of changes. 17 change blocks. 
28 lines changed or deleted 41 lines changed or added

This html diff was produced by rfcdiff 1.35. The latest version is available from http://tools.ietf.org/tools/rfcdiff/