idnits 2.17.1
draft-ietf-vcarddav-webdav-mkcol-06.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 :
----------------------------------------------------------------------------
-- The draft header indicates that this document updates RFC4918, but the
abstract doesn't seem to mention this, which it should.
-- The draft header indicates that this document updates RFC4791, but the
abstract doesn't seem to mention this, which it should.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
(Using the creation date from RFC4791, updated by this document, for
RFC5378 checks: 2004-06-24)
(Using the creation date from RFC4918, updated by this document, for
RFC5378 checks: 2002-02-20)
-- 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 (August 18, 2009) is 5363 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 (==), 4 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 Updates: 4791, 4918 August 18, 2009
5 (if approved)
6 Intended status: Standards Track
7 Expires: February 19, 2010
9 Extended MKCOL for WebDAV
10 draft-ietf-vcarddav-webdav-mkcol-06
12 Status of This Memo
14 This Internet-Draft is submitted to IETF in full conformance with the
15 provisions of BCP 78 and BCP 79. This document may contain material
16 from IETF Documents or IETF Contributions published or made publicly
17 available before November 10, 2008. The person(s) controlling the
18 copyright in some of this material may not have granted the IETF
19 Trust the right to allow modifications of such material outside the
20 IETF Standards Process. Without obtaining an adequate license from
21 the person(s) controlling the copyright in such materials, this
22 document may not be modified outside the IETF Standards Process, and
23 derivative works of it may not be created outside the IETF Standards
24 Process, except to format it for publication as an RFC or to
25 translate it into languages other than English.
27 Internet-Drafts are working documents of the Internet Engineering
28 Task Force (IETF), its areas, and its working groups. Note that
29 other groups may also distribute working documents as Internet-
30 Drafts.
32 Internet-Drafts are draft documents valid for a maximum of six months
33 and may be updated, replaced, or obsoleted by other documents at any
34 time. It is inappropriate to use Internet-Drafts as reference
35 material or to cite them other than as "work in progress."
37 The list of current Internet-Drafts can be accessed at
38 http://www.ietf.org/ietf/1id-abstracts.txt.
40 The list of Internet-Draft Shadow Directories can be accessed at
41 http://www.ietf.org/shadow.html.
43 This Internet-Draft will expire on February 19, 2010.
45 Copyright Notice
47 Copyright (c) 2009 IETF Trust and the persons identified as the
48 document authors. All rights reserved.
50 This document is subject to BCP 78 and the IETF Trust's Legal
51 Provisions Relating to IETF Documents in effect on the date of
52 publication of this document (http://trustee.ietf.org/license-info).
53 Please review these documents carefully, as they describe your rights
54 and restrictions with respect to this document.
56 Abstract
58 This specification extends the Web Distributed Authoring and
59 Versioning (WebDAV) MKCOL ("Make Collection") method to allow
60 collections of arbitrary resourcetype to be created and to allow
61 properties to be set at the same time.
63 Table of Contents
65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
66 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
67 3. WebDAV Extended MKCOL . . . . . . . . . . . . . . . . . . . . 4
68 3.1. Extended MKCOL Support . . . . . . . . . . . . . . . . . . 4
69 3.1.1. Example: Using OPTIONS for the Discovery of
70 Support for Extended MKCOL . . . . . . . . . . . . . . 5
71 3.2. Status Codes . . . . . . . . . . . . . . . . . . . . . . . 5
72 3.3. Additional Precondition for Extended MKCOL . . . . . . . . 5
73 3.4. Example: Successful Extended MKCOL Request . . . . . . . . 5
74 3.5. Example: Unsuccessful Extended MKCOL Request . . . . . . . 6
75 4. Using Extended MKCOL as an Alternative for MKxxx Methods . . . 8
76 4.1. MKCALENDAR alternative . . . . . . . . . . . . . . . . . . 8
77 4.1.1. Example: Using MKCOL instead of MKCALENDAR . . . . . . 8
78 5. XML Element Definitions . . . . . . . . . . . . . . . . . . . 10
79 5.1. mkcol XML Element . . . . . . . . . . . . . . . . . . . . 10
80 5.2. mkcol-response XML Element . . . . . . . . . . . . . . . . 10
81 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11
82 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
83 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11
84 9. Normative References . . . . . . . . . . . . . . . . . . . . . 11
85 Appendix A. Change History (to be removed prior to
86 publication as an RFC) . . . . . . . . . . . . . . . 12
88 1. Introduction
90 WebDAV [RFC4918] defines the HTTP [RFC2616] method MKCOL. This
91 method is used to create WebDAV collections on the server. However,
92 several WebDAV-based specifications (e.g., CalDAV [RFC4791]) define
93 "special" collections - ones which are identified by additional
94 values in the DAV:resourcetype property assigned to the collection
95 resource, or through other means. These "special" collections are
96 created by new methods (e.g., MKCALENDAR). The addition of a new
97 MKxxx method for each new "special" collection adds to server
98 complexity and is detrimental to overall reliability due to the need
99 to make sure intermediaries are aware of these methods.
101 This specification defines an extension to the WebDAV MKCOL method
102 that adds a request body allowing a client to specify WebDAV
103 properties to be set on the newly created collection or resource. In
104 particular, the DAV:resourcetype property can be used to create a
105 "special" collection, or other properties used to create a "special"
106 resource. This avoids the need to invent new MKxxx methods.
108 2. Conventions Used in This Document
110 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
111 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
112 document are to be interpreted as described in [RFC2119].
114 This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section
115 3.2) as a purely notational convention. WebDAV request and response
116 bodies cannot be validated by a DTD due to the specific extensibility
117 rules defined in Section 17 of [RFC4918] and due to the fact that all
118 XML elements defined by this specification use the XML namespace name
119 "DAV:". In particular:
121 1. element names use the "DAV:" namespace,
123 2. element ordering is irrelevant unless explicitly stated,
125 3. extension elements (elements not already defined as valid child
126 elements) may be added anywhere, except when explicitly stated
127 otherwise,
129 4. extension attributes (attributes not already defined as valid for
130 this element) may be added anywhere, except when explicitly
131 stated otherwise.
133 When an XML element type in the "DAV:" namespace is referenced in
134 this document outside of the context of an XML fragment, the string
135 "DAV:" will be prefixed to the element type.
137 This document inherits, and sometimes extends, DTD productions from
138 Section 14 of [RFC4918].
140 3. WebDAV Extended MKCOL
142 The WebDAV MKCOL request is extended to allow the inclusion of a
143 request body. The request body is an XML document containing a
144 single DAV:mkcol XML element as the root element. The Content-Type
145 request header MUST be set appropriately for an XML body (e.g., set
146 to "text/xml" or "application/xml"). XML-typed bodies for an MKCOL
147 request that do not have DAV:mkcol as the root element are reserved
148 for future usage.
150 One or more DAV:set XML elements may be included in the DAV:mkcol XML
151 element to allow setting properties on the collection as it is
152 created. In particular, to create a collection of a particular type,
153 the DAV:resourcetype XML element MUST be included in a DAV:set XML
154 element and MUST specify the expected resource type elements for the
155 new resource, that MUST include the DAV:collection element that needs
156 to be present for any WebDAV collection.
158 As per the PROPPATCH method ([RFC4918], Section 9.2), servers MUST
159 process any DAV:set instructions in document order (an exception to
160 the normal rule that ordering is irrelevant). If any one instruction
161 fails to execute successfully, all instructions MUST fail (i.e.,
162 either all succeed or all fail). Thus, if any error occurs during
163 processing, all executed instructions MUST be undone and a proper
164 error result returned. Failure to set a property value on the
165 collection MUST result in a failure of the overall MKCOL request -
166 i.e. the collection is not created.
168 The response to an extended MKCOL request MUST be an XML document
169 containing a single DAV:mkcol-response XML element, which MUST
170 contain DAV:propstat XML elements with the status of each property
171 when the request fails due to a failure to set one or more of the
172 properties specified in the request body. The server MAY return a
173 response body in the case where the request is successful, indicating
174 success for setting each property specified in the request body.
175 When an empty response body is returned with a success request status
176 code, the client can assume that all properties were set.
178 In all other respects the behavior of the extended MKCOL request
179 follows that of the standard MKCOL request.
181 3.1. Extended MKCOL Support
183 A server supporting the features described in this document, MUST
184 include "extended-mkcol" as a field in the DAV response header from
185 an OPTIONS request on any URI that supports use of the extended MKCOL
186 method.
188 3.1.1. Example: Using OPTIONS for the Discovery of Support for Extended
189 MKCOL
191 >> Request <<
193 OPTIONS /addressbooks/users/ HTTP/1.1
194 Host: addressbook.example.com
196 >> Response <<
198 HTTP/1.1 200 OK
199 Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
200 Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL
201 DAV: 1, 2, 3, access-control, extended-mkcol
202 Date: Sat, 11 Nov 2006 09:32:12 GMT
203 Content-Length: 0
205 3.2. Status Codes
207 As per Section 9.3.1 of [RFC4918].
209 3.3. Additional Precondition for Extended MKCOL
211 WebDAV ([RFC4918], Section 16) defines preconditions and
212 postconditions for request behavior. This specification adds the
213 following precondition for the extended MKCOL request.
215 Name: valid-resourcetype
217 Namespace: DAV:
219 Use with: Typically 403 (Forbidden)
221 Purpose: (precondition) -- The server MUST support the specified
222 resourcetype value for the specified collection.
224 3.4. Example: Successful Extended MKCOL Request
226 This example shows how the extended MKCOL request is used to create a
227 collection of a fictitious type "special-resource". The response
228 body is empty as the request completed successfully.
230 >> Request <<
232 MKCOL /home/special/ HTTP/1.1
233 Host: special.example.com
234 Content-Type: application/xml; charset="utf-8"
235 Content-Length: xxxx
237
238
240
241
242
243
244
245
246 Special Resource
247
248
249
251 >> Response <<
253 HTTP/1.1 201 Created
254 Cache-Control: no-cache
255 Date: Sat, 11 Nov 2006 09:32:12 GMT
257 3.5. Example: Unsuccessful Extended MKCOL Request
259 This example shows an attempt to use the extended MKCOL request to
260 create a collection of a fictitious type "special-resource", which is
261 not actually supported by the server. The response body shows that
262 an error occurred specifically with the DAV:resourcetype property.
264 >> Request <<
266 MKCOL /home/special/ HTTP/1.1
267 Host: special.example.com
268 Content-Type: application/xml; charset="utf-8"
269 Content-Length: xxxx
271
272
274
275
276
277
278
279
280 Special Resource
281
282
283
285 >> Response <<
287 HTTP/1.1 403 Forbidden
288 Cache-Control: no-cache
289 Date: Sat, 11 Nov 2006 09:32:12 GMT
290 Content-Type: application/xml; charset="utf-8"
291 Content-Length: xxxx
293
294
295
296
297
298
299 HTTP/1.1 403 Forbidden
300
301 Resource type is not
302 supported by this server
303
304
305
306
307
308 HTTP/1.1 424 Failed Dependency
309
310
312 4. Using Extended MKCOL as an Alternative for MKxxx Methods
314 One of the goals of this extension is to eliminate the need for other
315 extensions to define their own variant of MKCOL to create the special
316 collections they need. This extension can be used as an alternative
317 to existing MKxxx methods in other extensions as detailed below. If
318 a server supports this extension and the other extension listed, then
319 the server MUST support use of the extended MKCOL method to achieve
320 the same result as the MKxxx method of the other extension.
322 4.1. MKCALENDAR alternative
324 CalDAV defines the MKCALENDAR method to create a calendar collection
325 as well as set properties during creation ([RFC4791], Section 5.3.1).
327 The extended MKCOL method can be used instead by specifying both DAV:
328 collection and CALDAV:calendar-collection XML elements in the DAV:
329 resourcetype property, set during the extended MKCOL request.
331 4.1.1. Example: Using MKCOL instead of MKCALENDAR
333 The first example below shows an MKCALENDAR request containing a
334 CALDAV:mkcalendar XML element in the request body, and returning a
335 CALDAV:mkcalendar-response XML element in the response body.
337 >> MKCALENDAR Request <<
339 MKCALENDAR /home/lisa/calendars/events/ HTTP/1.1
340 Host: calendar.example.com
341 Content-Type: application/xml; charset="utf-8"
342 Content-Length: xxxx
344
345
347
348
349 Lisa's Events
350
351
352
353 >> MKCALENDAR Response <<
355 HTTP/1.1 201 Created
356 Cache-Control: no-cache
357 Date: Sat, 11 Nov 2006 09:32:12 GMT
358 Content-Type: application/xml; charset="utf-8"
359 Content-Length: xxxx
361
362
364
365
366
367
368 HTTP/1.1 200 OK
369
370
372 The second example shows the equivalent extended MKCOL request with
373 the same request and response XML elements.
375 >> MKCOL Request <<
377 MKCOL /home/lisa/calendars/events/ HTTP/1.1
378 Host: calendar.example.com
379 Content-Type: application/xml; charset="utf-8"
380 Content-Length: xxxx
382
383
385
386
387
388
389
390
391 Lisa's Events
392
393
394
395 >> MKCOL Response <<
397 HTTP/1.1 201 Created
398 Cache-Control: no-cache
399 Date: Sat, 11 Nov 2006 09:32:12 GMT
400 Content-Type: application/xml; charset="utf-8"
401 Content-Length: xxxx
403
404
406
407
408
409
410
411 HTTP/1.1 200 OK
412
413
415 5. XML Element Definitions
417 5.1. mkcol XML Element
419 Name: mkcol
421 Namespace: DAV:
423 Purpose: Used in a request to specify properties to be set in an
424 extended MKCOL request, as well as any additional information
425 needed when creating the resource.
427 Description: This XML element is a container for the information
428 required to modify the properties on a collection resource as it
429 is created in an extended MKCOL request.
431 Definition:
433
435 5.2. mkcol-response XML Element
437 Name: mkcol-response
439 Namespace: DAV:
441 Purpose: Used in a response to indicate the status of properties
442 that were set or failed to be set during an extended MKCOL
443 request.
445 Description: This XML element is a container for the information
446 returned about a resource that has been created in an extended
447 MKCOL request.
449 Definition:
451
453 6. Security Considerations
455 This extension does not introduce any new security concerns beyond
456 those already described in HTTP and WebDAV.
458 7. IANA Considerations
460 This document does not require any actions on the part of IANA.
462 8. Acknowledgments
464 Thanks to Bernard Desruisseaux, Mike Douglass, Alexey Melnikov,
465 Julian Reschke, and Simon Vaillancourt.
467 9. Normative References
469 [RFC2119] Bradner, S., "Key words for use in RFCs to
470 Indicate Requirement Levels", BCP 14,
471 RFC 2119, March 1997.
473 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk,
474 H., Masinter, L., Leach, P., and T. Berners-
475 Lee, "Hypertext Transfer Protocol --
476 HTTP/1.1", RFC 2616, June 1999.
478 [RFC4791] Daboo, C., Desruisseaux, B., and L.
479 Dusseault, "Calendaring Extensions to WebDAV
480 (CalDAV)", RFC 4791, March 2007.
482 [RFC4918] Dusseault, L., "HTTP Extensions for Web
483 Distributed Authoring and Versioning
484 (WebDAV)", RFC 4918, June 2007.
486 [W3C.REC-xml-20081126] Paoli, J., Yergeau, F., Bray, T., Sperberg-
487 McQueen, C., and E. Maler, "Extensible Markup
488 Language (XML) 1.0 (Fifth Edition)", World
489 Wide Web Consortium Recommendation REC-xml-
490 20081126, November 2008,
491 .
493 Appendix A. Change History (to be removed prior to publication as an
494 RFC)
496 Changes in -06:
498 1. Fixed section title.
500 2. Gen-ART review comments addressed.
502 3. Added "Updates 4791, 4918".
504 4. Tweaked examples.
506 Changes in -05:
508 1. Make response body optional in case of complete success.
510 2. Added an example of an error with extended MKCOL.
512 Changes in -04:
514 1. WGLC: minor wording tweaks.
516 2. WGLC: switch to using XML conventions text from RFC5323.
518 3. WGLC: MAY -> may in section 3/paragraph 2.
520 4. WGLC: mkcol-response DTD - removed ANY.
522 5. WGLC: updated to W3C.REC-xml-20081126 reference.
524 Changes in -03:
526 1. Boiler plate update.
528 Changes in -02:
530 1. Minor formatting/wording changes proposed by Julian Reschke were
531 applied.
533 2. Removed reference to DeltaV entirely as the spec no longer
534 replaces the MKxxx DeltaV defines.
536 3. Added Namespace definition to precondition.
538 4. Added reference to 4918 XML extensibility rules.
540 5. Added statement that DAV:collection must be present in DAV:
541 resourcetype in the request.
543 6. Added statement on use of DTD fragments.
545 7. Added statement about setting proper Content-Type for the MKCOL
546 body.
548 8. Added statement that MKCOL bodies using a different root element
549 are reserved for future extensions.
551 Changes in -01:
553 1. Fixed an example.
555 Changes in -00:
557 1. Removed MKACTIVITY and MKWORKSPACE replacement behavior.
559 2. Added valid-resourcetype precondition.
561 Author's Address
563 Cyrus Daboo
564 Apple Inc.
565 1 Infinite Loop
566 Cupertino, CA 95014
567 USA
569 EMail: cyrus@daboo.name
570 URI: http://www.apple.com/