draft-ietf-vcarddav-webdav-mkcol-01.txt   draft-ietf-vcarddav-webdav-mkcol-02.txt 
Network Working Group C. Daboo Network Working Group C. Daboo
Internet-Draft Apple Inc. Internet-Draft Apple Inc.
Intended status: Standards Track November 24, 2008 Intended status: Standards Track November 28, 2008
Expires: May 28, 2009 Expires: June 1, 2009
Extended MKCOL for WebDAV Extended MKCOL for WebDAV
draft-ietf-vcarddav-webdav-mkcol-01 draft-ietf-vcarddav-webdav-mkcol-02
Status of This Memo Status of This Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79. aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
skipping to change at page 1, line 34 skipping to change at page 1, line 34
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 May 28, 2009. This Internet-Draft will expire on June 1, 2009.
Abstract Abstract
This specification extends the WebDAV MKCOL method to allow This specification extends the Web Distributed Authoring and
collections of arbitrary resourcetype to be created and to allow Versioning (WebDAV) MKCOL method to allow collections of arbitrary
properties to be set at the same time. resourcetype to be created and to allow 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 . . . . . . . . . . . . . . . . . . . . 3 3. WebDAV extended MKCOL . . . . . . . . . . . . . . . . . . . . 3
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 . . . . . . . . . . . . . . 4 Support for Extended MKCOL . . . . . . . . . . . . . . 4
3.2. Status Codes . . . . . . . . . . . . . . . . . . . . . . . 4 3.2. Status Codes . . . . . . . . . . . . . . . . . . . . . . . 5
3.3. Additional Precondition for extended MKCOL . . . . . . . . 4 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 4. Replacing Existing MKxxx Methods . . . . . . . . . . . . . . . 6
4.1. MKCALENDAR replacement . . . . . . . . . . . . . . . . . . 6 4.1. MKCALENDAR Replacement . . . . . . . . . . . . . . . . . . 7
4.1.1. Example: Replacing MKCALENDAR with MKCOL . . . . . . . 6 4.1.1. Example: Replacing MKCALENDAR with MKCOL . . . . . . . 7
5. XML Element Definitions . . . . . . . . . . . . . . . . . . . 8 5. XML Element Definitions . . . . . . . . . . . . . . . . . . . 9
5.1. mkcol XML Element . . . . . . . . . . . . . . . . . . . . 8 5.1. mkcol XML Element . . . . . . . . . . . . . . . . . . . . 9
5.2. mkcol-response XML Element . . . . . . . . . . . . . . . . 9 5.2. mkcol-response XML Element . . . . . . . . . . . . . . . . 9
6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10
9. Normative References . . . . . . . . . . . . . . . . . . . . . 10 9. Normative References . . . . . . . . . . . . . . . . . . . . . 10
Appendix A. Change History (to be removed prior to Appendix A. Change History (to be removed prior to
publication as an RFC) . . . . . . . . . . . . . . . 10 publication as an RFC) . . . . . . . . . . . . . . . 11
1. Introduction 1. Introduction
WebDAV [RFC4918] defines an HTTP [RFC2616] method MKCOL. This method WebDAV [RFC4918] defines the HTTP [RFC2616] method MKCOL. This
is used to create WebDAV collections on the server. However, several method is used to create WebDAV collections on the server. However,
WebDAV-based specifications (e.g., DeltaV [RFC3253], CalDAV several WebDAV-based specifications (e.g., CalDAV [RFC4791]) define
[RFC4791]) define "special" collections or resources - ones which are "special" collections - ones which are identified by additional
identified by additional values in the DAV:resourcetype property values in the DAV:resourcetype property assigned to the collection
assigned to the collection resource, or through other means. These resource, or through other means. These "special" collections are
"special" collections are created by new methods (e.g., MKACTIVITY, created by new methods (e.g., MKCALENDAR). The addition of a new
MKWORKSPACE, MKCALENDAR). The addition of a new MKxxx method for MKxxx method for each new "special" collection adds to server
each new "special" collection or resource adds to server complexity complexity and is detrimental to overall reliability due to the need
and is detrimental to overall reliability due to the need to make to make sure intermediaries are aware of these methods.
sure intermediaries are aware of these methods.
This specification proposes an extension to the WebDAV MKCOL method This specification proposes 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
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
Definitions of XML elements in this document use XML element type
declarations (as found in XML Document Type Declarations), described
in Section 3.2 of [W3C.REC-xml-20060816].
When XML element types in the namespace "DAV:" are referenced in this When XML element types in the namespace "DAV:" are referenced in this
document outside of the context of an XML fragment, the string "DAV:" document outside of the context of an XML fragment, the string "DAV:"
will be prefixed to the element type names. will be prefixed to the element type names.
Processing of XML by clients and servers MUST follow the rules
described in Appendix A 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 at the top-level. One or more DAV:set single DAV:mkcol XML element as the root element. The Content-Type
XML elements MAY be included in the DAV:mkcol XML element to allow request header MUST be set appropriately for an XML body (e.g., set
setting properties on the collection as it is created. In to "text/xml" or "application/xml"). XML-typed bodies for an MKCOL
particular, to create a collection of a particular type, the DAV: request that do not have DAV:mkcol as the root element are reserved
resourcetype XML element MUST be included in a DAV:set XML element for future usage.
and MUST specify the correct resource type elements for the new
resource.
As per the PROPPATCH method, servers MUST process any DAV:set One or more DAV:set XML elements MAY be included in the DAV:mkcol XML
instructions in document order (an exception to the normal rule that element to allow setting properties on the collection as it is
ordering is irrelevant). Instructions MUST either all be executed or created. In particular, to create a collection of a particular type,
none executed. Thus, if any error occurs during processing, all the DAV:resourcetype XML element MUST be included in a DAV:set XML
executed instructions MUST be undone and a proper error result element and MUST specify the expected resource type elements for the
returned. Failure to set a property value on the collection MUST new resource, that MUST include the DAV:collection element that needs
result in a failure of the overall MKCOL request. to be present for any WebDAV collection.
As per the PROPPATCH method ([RFC4918], Section 9.2), servers MUST
process any DAV:set instructions in document order (an exception to
the normal rule that ordering is irrelevant). Instructions MUST
either all be executed or none executed. Thus, if any error occurs
during 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.
If a server attempts to make any of the property changes in an If a server attempts to make any of the property changes in an
extended MKCOL request (i.e., the request is not rejected for high- extended MKCOL request (i.e., the request is not rejected for high-
level errors before processing the body), the response MUST be an XML level errors before processing the body), the response MUST be an XML
document containing a single DAV:mkcol-response XML element, which document containing a single DAV:mkcol-response XML element, which
MUST contain DAV:propstat XML elements with the status of each MUST contain DAV:propstat XML elements with the status of each
property. property.
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 resource that supports use of the extended an OPTIONS request on any URI that supports use of the extended MKCOL
MKCOL method. method.
3.1.1. Example: Using OPTIONS for the Discovery of Support for extended 3.1.1. Example: Using OPTIONS for the Discovery of Support for Extended
MKCOL MKCOL
>> Request << >> Request <<
OPTIONS /addressbooks/users/ HTTP/1.1 OPTIONS /addressbooks/users/ HTTP/1.1
Host: addressbook.example.com Host: addressbook.example.com
>> Response << >> Response <<
HTTP/1.1 200 OK HTTP/1.1 200 OK
Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL
DAV: 1, 2, 3, access-control, extended-mkcol DAV: 1, 2, 3, access-control, extended-mkcol
Date: Sat, 11 Nov 2006 09:32:12 GMT Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Length: 0 Content-Length: 0
3.2. Status Codes 3.2. Status Codes
skipping to change at page 4, line 45 skipping to change at page 5, line 17
Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL
DAV: 1, 2, 3, access-control, extended-mkcol DAV: 1, 2, 3, access-control, extended-mkcol
Date: Sat, 11 Nov 2006 09:32:12 GMT Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Length: 0 Content-Length: 0
3.2. Status Codes 3.2. Status Codes
As per Section 9.3.1 of [RFC4918]. As per Section 9.3.1 of [RFC4918].
3.3. Additional Precondition for extended MKCOL 3.3. Additional Precondition for Extended MKCOL
WebDAV [RFC4918] (Section 16) defines preconditions and WebDAV ([RFC4918], Section 16) defines preconditions and
postconditions for request behavior. This specification adds the postconditions for request behavior. This specification adds the
following precondition for the extended MKCOL request. following precondition for the extended MKCOL request.
Name: valid-resourcetype Name: valid-resourcetype
Use with: Typically 403 Forbidden Namespace: DAV:
Purpose: (precondition) -- The server does not support the specified Use with: Typically 403 (Forbidden)
resourcetype value for any collections.
3.4. Example: Successful extended MKCOL Request Purpose: (precondition) -- The server MUST support the specified
resourcetype value for the specified collection.
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".
>> 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
skipping to change at page 6, line 23 skipping to change at page 6, line 45
<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: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>
</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
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 Replacement
CalDAV [RFC4791] defines the MKCALENDAR method to create a calendar CalDAV defines the MKCALENDAR method to create a calendar collection
collection as well as set properties during creation. 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. The
skipping to change at page 9, line 18 skipping to change at page 9, line 42
Purpose: Used in a request to specify properties to be set in an Purpose: Used in a request to specify properties to be set in an
extended MKCOL request, as well as any additional information extended MKCOL request, as well as any additional information
needed when creating the resource. needed when creating the resource.
Description: This XML element is a container for the information Description: This XML element is a container for the information
required to modify the properties on a collection resource as it required to modify the properties on a collection resource as it
is created in an extended MKCOL request. is created in an extended MKCOL request.
Definition: Definition:
<!ELEMENT mkcol (set+, ANY)> <!ELEMENT mkcol (set+)>
5.2. mkcol-response XML Element 5.2. mkcol-response XML Element
Name: mkcol-response Name: mkcol-response
Namespace: DAV: Namespace: DAV:
Purpose: Used in a response to indicate the status of properties Purpose: Used in a response to indicate the status of properties
that were set or failed to be set during an extended MKCOL that were set or failed to be set during an extended MKCOL
request. request.
skipping to change at page 10, line 7 skipping to change at page 10, line 33
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
Several people suggested this approach, including Julian Reschke and Several people suggested this approach, including Julian Reschke and
Bernard Desruisseaux. Thanks also to Mike Douglass. Bernard Desruisseaux. Thanks also to Mike Douglass.
9. Normative References 9. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to
Requirement Levels", BCP 14, RFC 2119, March 1997. Indicate Requirement Levels", BCP 14,
RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext H., Masinter, L., Leach, P., and T. Berners-
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Lee, "Hypertext Transfer Protocol --
HTTP/1.1", RFC 2616, June 1999.
[RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. [RFC4791] Daboo, C., Desruisseaux, B., and L.
Whitehead, "Versioning Extensions to WebDAV Dusseault, "Calendaring Extensions to WebDAV
(Web Distributed Authoring and Versioning)", RFC 3253, (CalDAV)", RFC 4791, March 2007.
March 2002.
[RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, [RFC4918] Dusseault, L., "HTTP Extensions for Web
"Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, Distributed Authoring and Versioning
March 2007. (WebDAV)", RFC 4918, June 2007.
[RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed [W3C.REC-xml-20060816] Paoli, J., Yergeau, F., Bray, T., Sperberg-
Authoring and Versioning (WebDAV)", RFC 4918, June 2007. McQueen, C., and E. Maler, "Extensible Markup
Language (XML) 1.0 (Fourth Edition)", World
Wide Web Consortium Recommendation REC-xml-
20060816, August 2006,
<http://www.w3.org/TR/2006/REC-xml-20060816>.
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 from -01:
1. Minor formatting/wording changes proposed by Julian Reschke were
applied.
2. Removed reference to DeltaV entirely as the spec no longer
replaces the MKxxx DeltaV defines.
3. Added Namespace definition to precondition.
4. Added reference to 4918 XML extensibility rules.
5. Added statement that DAV:collection must be present in DAV:
resourcetype in the request.
6. Added statement on use of DTD fragments.
7. Added statement about setting proper Content-Type for the MKCOL
body.
8. Added statement that MKCOL bodies using a different root element
are reserved for future extensions.
Changes from -00: Changes from -00:
1. Fixed an example. 1. Fixed an example.
Changes from draft-daboo-webdav-mkcol-00: Changes from draft-daboo-webdav-mkcol-00:
1. Removed MKACTIVITY and MKWORKSPACE replacement behavior. 1. Removed MKACTIVITY and MKWORKSPACE replacement behavior.
2. Added valid-resourcetype precondition. 2. Added valid-resourcetype precondition.
 End of changes. 30 change blocks. 
74 lines changed or deleted 116 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/