draft-ietf-vcarddav-webdav-mkcol-04.txt   draft-ietf-vcarddav-webdav-mkcol-05.txt 
Network Working Group C. Daboo Network Working Group C. Daboo
Internet-Draft Apple Inc. Internet-Draft Apple Inc.
Intended status: Standards Track March 9, 2009 Intended status: Standards Track July 13, 2009
Expires: September 10, 2009 Expires: January 14, 2010
Extended MKCOL for WebDAV Extended MKCOL for WebDAV
draft-ietf-vcarddav-webdav-mkcol-04 draft-ietf-vcarddav-webdav-mkcol-05
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 42
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 September 10, 2009. This Internet-Draft will expire on January 14, 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
skipping to change at page 2, line 27 skipping to change at page 2, line 27
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
4. Replacing Existing MKxxx Methods . . . . . . . . . . . . . . . 6 3.5. Example: Successful Extended MKCOL Request . . . . . . . . 6
4.1. MKCALENDAR Replacement . . . . . . . . . . . . . . . . . . 7 4. Replacing Existing MKxxx Methods . . . . . . . . . . . . . . . 8
4.1.1. Example: Replacing MKCALENDAR with MKCOL . . . . . . . 7 4.1. MKCALENDAR Replacement . . . . . . . . . . . . . . . . . . 8
5. XML Element Definitions . . . . . . . . . . . . . . . . . . . 9 4.1.1. Example: Replacing MKCALENDAR with MKCOL . . . . . . . 8
5.1. mkcol XML Element . . . . . . . . . . . . . . . . . . . . 9 5. XML Element Definitions . . . . . . . . . . . . . . . . . . . 10
5.2. mkcol-response XML Element . . . . . . . . . . . . . . . . 9 5.1. mkcol XML Element . . . . . . . . . . . . . . . . . . . . 10
6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 5.2. mkcol-response XML Element . . . . . . . . . . . . . . . . 10
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
9. Normative References . . . . . . . . . . . . . . . . . . . . . 10 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 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) . . . . . . . . . . . . . . . 11 publication as an RFC) . . . . . . . . . . . . . . . 12
1. Introduction 1. Introduction
WebDAV [RFC4918] defines the HTTP [RFC2616] method MKCOL. This WebDAV [RFC4918] defines the HTTP [RFC2616] method MKCOL. This
method is used to create WebDAV collections on the server. However, method is used to create WebDAV collections on the server. However,
several WebDAV-based specifications (e.g., CalDAV [RFC4791]) define several WebDAV-based specifications (e.g., CalDAV [RFC4791]) define
"special" collections - ones which are identified by additional "special" collections - ones which are identified by additional
values in the DAV:resourcetype property assigned to the collection values in the DAV:resourcetype property assigned to the collection
resource, or through other means. These "special" collections are resource, or through other means. These "special" collections are
created by new methods (e.g., MKCALENDAR). The addition of a new created by new methods (e.g., MKCALENDAR). The addition of a new
MKxxx method for each new "special" collection adds to server MKxxx method for each new "special" collection adds to server
complexity and is detrimental to overall reliability due to the need complexity and is detrimental to overall reliability due to the need
to make sure intermediaries are aware of these methods. to make sure intermediaries are aware of these methods.
This specification defined an extension to the WebDAV MKCOL method This specification defines an extension to the WebDAV MKCOL method
that adds a request body allowing a client to specify WebDAV that adds a request body allowing a client to specify WebDAV
properties to be set on the newly created collection or resource. In properties to be set on the newly created collection or resource. In
particular, the DAV:resourcetype property can be used to create a particular, the DAV:resourcetype property can be used to create a
"special" collection, or other properties used to create a "special" "special" collection, or other properties used to create a "special"
resource. This avoids the need to invent new MKxxx methods. resource. This avoids the need to invent new MKxxx methods.
2. Conventions Used in This Document 2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
skipping to change at page 4, line 32 skipping to change at page 4, line 32
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). Instructions MUST
either all be executed or none executed. Thus, if any error occurs either all be executed or none executed. Thus, if any error occurs
during processing, all executed instructions MUST be undone and a during processing, all executed instructions MUST be undone and a
proper error result returned. Failure to set a property value on the 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.
If a server attempts to make any of the property changes in an The response to an extended MKCOL request MUST be an XML document
extended MKCOL request (i.e., the request is not rejected for high- containing a single DAV:mkcol-response XML element, which MUST
level errors before processing the body), the response MUST be an XML contain DAV:propstat XML elements with the status of each property
document containing a single DAV:mkcol-response XML element, which when the request fails due to a failure to set one or more of the
MUST contain DAV:propstat XML elements with the status of each properties specified in the request body. The server MAY return a
property. response body in the case where the request is successful, indicating
success for setting each property specified in the request body.
When an empty response body is returned with a success request status
code, the client can assume that all properties were set.
In all other respects the behavior of the extended MKCOL request In all other respects the behavior of the extended MKCOL request
follows that of the standard MKCOL request. follows that of the standard MKCOL request.
3.1. Extended MKCOL Support 3.1. Extended MKCOL Support
A server supporting the features described in this document, MUST A server supporting the features described in this document, MUST
include "extended-mkcol" as a field in the DAV response header from include "extended-mkcol" as a field in the DAV response header from
an OPTIONS request on any URI that supports use of the extended MKCOL an OPTIONS request on any URI that supports use of the extended MKCOL
method. method.
skipping to change at page 5, line 44 skipping to change at page 5, line 45
Namespace: DAV: Namespace: DAV:
Use with: Typically 403 (Forbidden) Use with: Typically 403 (Forbidden)
Purpose: (precondition) -- The server MUST support the specified Purpose: (precondition) -- The server MUST support the specified
resourcetype value for the specified collection. resourcetype value for the specified collection.
3.4. Example: Successful Extended MKCOL Request 3.4. Example: Successful Extended MKCOL Request
This example shows how the extended MKCOL request is used to create a This example shows how the extended MKCOL request is used to create a
collection of a fictitious type "special-resource". collection of a fictitious type "special-resource". The response
body is empty as the request completed successfully.
>> Request << >> Request <<
MKCOL /home/special/ HTTP/1.1 MKCOL /home/special/ HTTP/1.1
Host: special.example.com Host: special.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:"
skipping to change at page 6, line 31 skipping to change at page 6, line 31
<D:displayname>Special Resource</D:displayname> <D:displayname>Special Resource</D:displayname>
</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
This example shows an attempt to use the extended MKCOL request to
create a collection of a fictitious type "special-resource", which is
not actually supported by the server. The response body shows that
an error occurred specifically with the DAV:resourcetype property.
>> Request <<
MKCOL /home/special/ HTTP/1.1
Host: special.example.com
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:mkcol xmlns:D="DAV:"
xmlns:E="http://example.com/ns/">
<D:set>
<D:prop>
<D:resourcetype>
<D:collection/>
<E:special-resource/>
</D:resourcetype>
<D:displayname>Special Resource</D:displayname>
</D:prop>
</D:set>
</D:mkcol>
>> Response <<
HTTP/1.1 403 Forbidden
Cache-Control: no-cache
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
<?xml version="1.0" encoding="utf-8" ?> <?xml version="1.0" encoding="utf-8" ?>
<D:mkcol-response xmlns:D="DAV:"> <D:mkcol-response xmlns:D="DAV:">
<D:propstat> <D:propstat>
<D:prop> <D:prop>
<D:resourcetype/> <D:resourcetype/>
</D:prop>
<D:status>HTTP/1.1 403 Forbidden</D:status>
<D:error><D:valid-resourcetype /></D:error>
<D:responsedescription>Resource type is not
supported by this server</D:responsedescription>
</D:propstat>
<D:propstat>
<D:prop>
<D:displayname/> <D:displayname/>
</D:prop> </D:prop>
<D:status>HTTP/1.1 200 OK</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. Replacing Existing 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 to replace
existing MKxxx methods in other extensions as detailed below. If a existing MKxxx methods in other extensions as detailed below. If a
server supports this extension and the other extension listed, then server supports this extension and the other extension listed, then
skipping to change at page 7, line 19 skipping to change at page 8, line 28
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: Replacing MKCALENDAR with MKCOL
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. The CALDAV:mkcalendar-response XML element in the response body.
second example shows the equivalent extended MKCOL request with the
same request and response XML elements.
>> 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"
Content-Length: xxxx Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?> <?xml version="1.0" encoding="utf-8" ?>
<C:mkcalendar xmlns:D="DAV:" <C:mkcalendar xmlns:D="DAV:"
skipping to change at page 8, line 23 skipping to change at page 9, line 23
<C:mkcalendar-response xmlns:D="DAV:" <C:mkcalendar-response xmlns:D="DAV:"
xmlns:C="urn:ietf:params:xml:ns:caldav"> xmlns:C="urn:ietf:params:xml:ns:caldav">
<D:propstat> <D:propstat>
<D:prop> <D:prop>
<D:displayname/> <D:displayname/>
</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 same request and response XML elements.
>> MKCOL Request << >> MKCOL Request <<
MKCOL /home/cyrus/calendars/events/ HTTP/1.1 MKCOL /home/cyrus/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">
skipping to change at page 11, 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 -05:
1. Make response body optional in case of complete success.
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.
2. WGLC: switch to using XML conventions text from [RFC5323]. 2. WGLC: switch to using XML conventions text from RFC5323.
3. WGLC: MAY -> may in section 3/paragraph 2. 3. WGLC: MAY -> may in section 3/paragraph 2.
4. WGLC: mkcol-response DTD - removed ANY. 4. WGLC: mkcol-response DTD - removed ANY.
5. WGLC: updated to W3C.REC-xml-20081126 reference. 5. WGLC: updated to W3C.REC-xml-20081126 reference.
Changes in -03: Changes in -03:
1. Boiler plate update. 1. Boiler plate update.
 End of changes. 16 change blocks. 
29 lines changed or deleted 84 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/