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/