RFC 5689

Extended MKCOL for Web Distributed Authoring and Versioning (WebDAV)

📅 published September 2009, from ietf

Extended MKCOL for Web Distributed Authoring and Versioning (WebDAV) 🎀

Okay bestie, this one is by C. Daboo at Apple Inc., it's a Standards Track doc from September 2009, filed under the Network Working Group, and it's giving RFC 5689 ✨. It updates RFC 4791 and RFC 4918, so it's extending stuff that already exists instead of starting from scratch. Iconic behaviour from a spec 💅

Abstract

Okay so the vibe here is that this spec extends the WebDAV MKCOL (Make Collection) method 🧚 It lets you create collections of arbitrary resourcetype AND set properties at the same time, all in one request. Main character energy, no cap 💖

Status of This Memo

This document is an Internet standards track protocol for the Internet community, and it's basically asking for discussion and suggestions for improvements 🫶 If you want the standardization state and status of this protocol, go check the current edition of the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited, so share it with everyone 🌸

Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved. ✨

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review those documents carefully, because they describe your rights and restrictions with respect to this document, and that's lowkey important 🙈 Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they're provided without warranty as described in the BSD License.

This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English. Very serious legal energy here 💀

Table of Contents

1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
2.  Conventions Used in This Document  . . . . . . . . . . . . . .  3
3.  WebDAV Extended MKCOL  . . . . . . . . . . . . . . . . . . . .  4
  3.1.  Extended MKCOL Support . . . . . . . . . . . . . . . . . .  5
    3.1.1.  Example: Using OPTIONS for the Discovery of
            Support for Extended MKCOL . . . . . . . . . . . . . .  5
  3.2.  Status Codes . . . . . . . . . . . . . . . . . . . . . . .  5
  3.3.  Additional Precondition for Extended MKCOL . . . . . . . .  5
  3.4.  Example: Successful Extended MKCOL Request . . . . . . . .  6
  3.5.  Example: Unsuccessful Extended MKCOL Request . . . . . . .  6
4.  Using Extended MKCOL as an Alternative for MKxxx Methods . . .  8
  4.1.  MKCALENDAR Alternative . . . . . . . . . . . . . . . . . .  8
    4.1.1.  Example: Using MKCOL Instead of MKCALENDAR . . . . . .  8
5.  XML Element Definitions  . . . . . . . . . . . . . . . . . . . 10
  5.1.  mkcol XML Element  . . . . . . . . . . . . . . . . . . . . 10
  5.2.  mkcol-response XML Element . . . . . . . . . . . . . . . . 10
6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 11
7.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 11
8.  Normative References . . . . . . . . . . . . . . . . . . . . . 11

1. Introduction ✨

Okay so WebDAV [RFC4918] defines the HTTP [RFC2616] method MKCOL, and that's the one used to create WebDAV collections on the server. BUT, several WebDAV-based specs (e.g., CalDAV [RFC4791]) define "special" collections, which are the ones identified by extra values in the DAV:resourcetype property on the collection resource, or by other means 🦋 Those special collections get created by brand new methods (like MKCALENDAR). Adding a new MKxxx method for every new "special" collection makes the server more complicated, and it hurts overall reliability too, because every intermediary has to be made aware of those methods. Not ideal, bestie 😭

So this spec adds a request body to the WebDAV MKCOL method, so the client can say which WebDAV properties should be set on the newly created collection or resource. The DAV:resourcetype property can make a "special" collection, and other properties can make a "special" resource. No need to invent new MKxxx methods, periodt 💅

2. Conventions Used in This Document 🌈

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. That's the BCP 14 key word stuff, so read those carefully 🫶

This doc uses XML DTD fragments (Section 3.2 of [W3C.REC-xml-20081126]) as a purely notational convention. WebDAV request and response bodies can't be validated by a DTD, because of the specific extensibility rules in Section 17 of [RFC4918], and because every XML element this spec defines uses the XML namespace name "DAV:". Here's the deal:

  1. Element names use the "DAV:" namespace.
  2. Element ordering is irrelevant unless explicitly stated.
  3. Extension elements (elements not already defined as valid child elements) may be added anywhere, except when explicitly stated otherwise.
  4. Extension attributes (attributes not already defined as valid for this element) may be added anywhere, except when explicitly stated otherwise.

When an XML element type in the "DAV:" namespace is referenced in this document outside of the context of an XML fragment, the string "DAV:" will be prefixed to the element type. So you'll always know which namespace is being talked about 🎀

This document inherits, and sometimes extends, DTD productions from Section 14 of [RFC4918]. Basically it's building on top of what's already there.

3. WebDAV Extended MKCOL 🍓

Okay so the WebDAV MKCOL request gets extended to allow a request body. The request body is an XML document with a 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 to "text/xml" or "application/xml"). XML-typed bodies for an MKCOL request that don't have DAV:mkcol as the root element are reserved for future usage, so hands off those for now 🔥

One or more DAV:set XML elements may be included in the DAV:mkcol XML element, so you can set properties on the collection as it gets created. To make a collection of a particular type, the DAV:resourcetype XML element MUST be included in a DAV:set XML element, and it MUST specify the expected resource type elements for the new resource. Those MUST include the DAV:collection element, which needs to be present for any WebDAV collection, no exceptions 👑

As per the PROPPATCH method (Section 9.2 of [RFC4918]), servers MUST process any DAV:set instructions in document order (this is an exception to the normal rule that ordering is irrelevant). If any one instruction fails to execute successfully, all instructions MUST fail. In other words, either all succeed or all fail. So if any error happens during processing, all executed instructions MUST be undone, and a proper error result gets returned. Failure to set a property value on the collection MUST result in a failure of the overall MKCOL request, meaning the collection is not created 😭

The response to an extended MKCOL request MUST be an XML document with a single DAV:mkcol-response XML element. When the request fails because one or more of the properties in the request body couldn't be set, that element MUST contain DAV:propstat XML elements showing the status of each property. The server MAY return a response body when the request succeeds, indicating success for setting each property in the request body. When an empty response body comes back 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 follows that of the standard MKCOL request. Simple, iconic 💖

3.1. Extended MKCOL Support 🦋

A server supporting the features in this document MUST 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 method. Basically, if you can use extended MKCOL there, the server has to say so 🫶

3.1.1. Example: Using OPTIONS for the Discovery of Support for Extended MKCOL

Here's a request and response so you can see what the discovery looks like 👀

>> Request <<

OPTIONS /addressbooks/users/ HTTP/1.1
Host: addressbook.example.com

>> Response <<

HTTP/1.1 200 OK
Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL
DAV: 1, 2, 3, access-control, extended-mkcol
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Length: 0

3.2. Status Codes 🌸

Status codes work exactly as Section 9.3.1 of [RFC4918] says, so nothing new to memorize here 🧚

3.3. Additional Precondition for Extended MKCOL 🌈

WebDAV ([RFC4918], Section 16) defines preconditions and postconditions for request behavior. This spec adds the following precondition for the extended MKCOL request, so pay attention:

Name:  valid-resourcetype

Namespace:  DAV:

Use with:  Typically 403 (Forbidden)

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 makes a collection of a fictitious type "special-resource". The response body is empty because the request completed successfully, which is the good ending we love to see 🎀

>> 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 201 Created
Cache-Control: no-cache
Date: Sat, 11 Nov 2006 09:32:12 GMT

3.5. Example: Unsuccessful Extended MKCOL Request 🚫

okay so this one is a fail example and I'm obsessed with how clearly it shows the error 😭. We try to make a collection of a made up type called "special-resource" 🧚, which the server does not support lol. The response body tells us the problem is specifically with the DAV:resourcetype property, so the server basically points at the exact thing that went wrong. Iconic debugging energy 💅

>> 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-Length: xxxx

<?xml version="1.0" encoding="utf-8" ?>
<D:mkcol-response xmlns:D="DAV:">
  <D:propstat>
    <D:prop>
      <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:prop>
    <D:status>HTTP/1.1 424 Failed Dependency</D:status>
  </D:propstat>
</D:mkcol-response>

4. Using Extended MKCOL as an Alternative for MKxxx Methods 🦋

okay so a big goal of this extension is to stop every other extension from inventing its own MKCOL twin just to make the special collections it needs 🙅‍♀️. Instead, this extension can be used as an alternative to the existing MKxxx methods in other extensions, as detailed below. Now the big rule ✨: if a server supports this extension and the other extension listed, then the server MUST support use of the extended MKCOL method to achieve the same result as the MKxxx method of the other extension. No skipping, bestie 🫶

4.1. MKCALENDAR Alternative 📅

CalDAV defines the MKCALENDAR method to create a calendar collection, and it also lets you set properties during creation (Section 5.3.1 of [RFC4791]). Classic CalDAV behaviour 🌸

The extended MKCOL method can be used instead by specifying both DAV: collection and CALDAV:calendar-collection XML elements in the DAV: resourcetype property, set during the extended MKCOL request. So instead of calling MKCALENDAR, you just put both of those elements in resourcetype with an extended MKCOL, and it's giving the same vibe 💜

4.1.1. Example: Using MKCOL Instead of MKCALENDAR 🎀

the first example is an MKCALENDAR request with a CALDAV:mkcalendar XML element in the request body, and the server answers with a CALDAV:mkcalendar-response XML element in the response body. Here's the classic way 💅

>> MKCALENDAR Request <<

MKCALENDAR /home/lisa/calendars/events/ HTTP/1.1
Host: calendar.example.com
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx

<?xml version="1.0" encoding="utf-8" ?>
<C:mkcalendar xmlns:D="DAV:"
              xmlns:C="urn:ietf:params:xml:ns:caldav">
  <D:set>
    <D:prop>
      <D:displayname>Lisa's Events</D:displayname>
    </D:prop>
  </D:set>
</C:mkcalendar>
>> MKCALENDAR Response <<

HTTP/1.1 201 Created
Cache-Control: no-cache
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx

<?xml version="1.0" encoding="utf-8" ?>
<C:mkcalendar-response xmlns:D="DAV:"
              xmlns:C="urn:ietf:params:xml:ns:caldav">
  <D:propstat>
    <D:prop>
      <D:displayname/>
    </D:prop>
    <D:status>HTTP/1.1 200 OK</D:status>
  </D:propstat>
</C:mkcalendar-response>

the second example is the equivalent extended MKCOL request, with the same request and response XML elements. Same result, different route 🦋

>> MKCOL Request <<

MKCOL /home/lisa/calendars/events/ HTTP/1.1
Host: calendar.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:C="urn:ietf:params:xml:ns:caldav">
  <D:set>
    <D:prop>
      <D:resourcetype>
        <D:collection/>
        <C:calendar/>
      </D:resourcetype>
      <D:displayname>Lisa's Events</D:displayname>
    </D:prop>
  </D:set>
</D:mkcol>
>> MKCOL Response <<

HTTP/1.1 201 Created
Cache-Control: no-cache
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx

<?xml version="1.0" encoding="utf-8" ?>
<D:mkcol-response xmlns:D="DAV:"
              xmlns:C="urn:ietf:params:xml:ns:caldav">
  <D:propstat>
    <D:prop>
      <D:resourcetype/>
      <D:displayname/>
    </D:prop>
    <D:status>HTTP/1.1 200 OK</D:status>
  </D:propstat>
</D:mkcol-response>

5. XML Element Definitions 🧾

5.1. mkcol XML Element 💖

Name: mkcol

Namespace: DAV:

Purpose: this element is used in a request to specify the properties to be set in an extended MKCOL request, plus any extra info needed when the resource gets created ✨

Description: this XML element is a container for the info needed to modify the properties on a collection resource as it's being created in an extended MKCOL request 🌷

Definition:

<!ELEMENT mkcol (set+)>

5.2. mkcol-response XML Element 🌈

Name: mkcol-response

Namespace: DAV:

Purpose: this element is used in a response to show the status of the properties that were set, or that failed to be set, during an extended MKCOL request 🍓

Description: this XML element is a container for the info returned about a resource that has been created in an extended MKCOL request 🧚

Definition:

<!ELEMENT mkcol-response (propstat+)>

6. Security Considerations 🔐

⚠️ okay bestie, pay attention for a sec: this extension does not introduce any new security concerns beyond those already described in HTTP [RFC2616] and WebDAV [RFC4918]. So the security story is the same as those specs, nothing new added here 🙈

7. Acknowledgments 🫶

Thanks to Bernard Desruisseaux, Mike Douglass, Alexey Melnikov, Julian Reschke, and Simon Vaillancourt. The whole squad 👑

8. Normative References 📚

  • [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
  • [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
  • [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, March 2007.
  • [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
  • [W3C.REC-xml-20081126] Maler, E., Yergeau, F., Paoli, J., Bray, T., and C. Sperberg-McQueen, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC-xml-20081126, November 2008, <http://www.w3.org/TR/2008/REC-xml-20081126>.

Author's Address 💌

Cyrus Daboo
Apple Inc.
1 Infinite Loop
Cupertino, CA  95014
USA

EMail: cyrus@daboo.name
URI:   http://www.apple.com/

That's the whole RFC, bestie! 🌈✨💅 Cyrus really said "reuse what already exists" and I respect the hustle 🦋🎀

📦 where this page comes from