RFC 4791
Calendaring Extensions to WebDAV (CalDAV)
Pages: 107
Proposed Standard
→ Errata
Updated by: 5689 6638 6764 7809 7953 8996
Proposed Standard
→ Errata
Updated by: 5689 6638 6764 7809 7953 8996
Part 1 of 5 – Pages 1 to 11
Network Working Group C. Daboo Request for Comments: 4791 Apple Category: Standards Track B. Desruisseaux Oracle L. Dusseault CommerceNet March 2007 Calendaring Extensions to WebDAV (CalDAV) Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The IETF Trust (2007).Abstract
This document defines extensions to the Web Distributed Authoring and Versioning (WebDAV) protocol to specify a standard way of accessing, managing, and sharing calendaring and scheduling information based on the iCalendar format. This document defines the "calendar-access" feature of CalDAV.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 1.2. XML Namespaces and Processing . . . . . . . . . . . . . . 5 1.3. Method Preconditions and Postconditions . . . . . . . . . 6 2. Requirements Overview . . . . . . . . . . . . . . . . . . . . 6 3. Calendaring Data Model . . . . . . . . . . . . . . . . . . . . 7 3.1. Calendar Server . . . . . . . . . . . . . . . . . . . . . 7 3.2. Recurrence and the Data Model . . . . . . . . . . . . . . 8 4. Calendar Resources . . . . . . . . . . . . . . . . . . . . . . 9 4.1. Calendar Object Resources . . . . . . . . . . . . . . . . 9 4.2. Calendar Collection . . . . . . . . . . . . . . . . . . . 10 5. Calendar Access Feature . . . . . . . . . . . . . . . . . . . 11 5.1. Calendar Access Support . . . . . . . . . . . . . . . . . 11 5.1.1. Example: Using OPTIONS for the Discovery of Calendar Access Support . . . . . . . . . . . . . . . 12 5.2. Calendar Collection Properties . . . . . . . . . . . . . . 12 5.2.1. CALDAV:calendar-description Property . . . . . . . . . 12 5.2.2. CALDAV:calendar-timezone Property . . . . . . . . . . 13 5.2.3. CALDAV:supported-calendar-component-set Property . . . 14 5.2.4. CALDAV:supported-calendar-data Property . . . . . . . 15 5.2.5. CALDAV:max-resource-size Property . . . . . . . . . . 16 5.2.6. CALDAV:min-date-time Property . . . . . . . . . . . . 17 5.2.7. CALDAV:max-date-time Property . . . . . . . . . . . . 18 5.2.8. CALDAV:max-instances Property . . . . . . . . . . . . 19 5.2.9. CALDAV:max-attendees-per-instance Property . . . . . . 19 5.2.10. Additional Precondition for PROPPATCH . . . . . . . . 20 5.3. Creating Resources . . . . . . . . . . . . . . . . . . . . 20 5.3.1. MKCALENDAR Method . . . . . . . . . . . . . . . . . . 20 5.3.1.1. Status Codes . . . . . . . . . . . . . . . . . . . 22 5.3.1.2. Example: Successful MKCALENDAR Request . . . . . . 23 5.3.2. Creating Calendar Object Resources . . . . . . . . . . 25 5.3.2.1. Additional Preconditions for PUT, COPY, and MOVE . . . . . . . . . . . . . . . . . . . . . . . 26 5.3.3. Non-Standard Components, Properties, and Parameters . 28 5.3.4. Calendar Object Resource Entity Tag . . . . . . . . . 28 6. Calendaring Access Control . . . . . . . . . . . . . . . . . . 29 6.1. Calendaring Privilege . . . . . . . . . . . . . . . . . . 29 6.1.1. CALDAV:read-free-busy Privilege . . . . . . . . . . . 29 6.2. Additional Principal Property . . . . . . . . . . . . . . 30 6.2.1. CALDAV:calendar-home-set Property . . . . . . . . . . 30 7. Calendaring Reports . . . . . . . . . . . . . . . . . . . . . 31 7.1. REPORT Method . . . . . . . . . . . . . . . . . . . . . . 31 7.2. Ordinary Collections . . . . . . . . . . . . . . . . . . . 31 7.3. Date and Floating Time . . . . . . . . . . . . . . . . . . 32 7.4. Time Range Filtering . . . . . . . . . . . . . . . . . . . 32 7.5. Searching Text: Collations . . . . . . . . . . . . . . . . 33
7.5.1. CALDAV:supported-collation-set Property . . . . . . . 34
7.6. Partial Retrieval . . . . . . . . . . . . . . . . . . . . 34
7.7. Non-Standard Components, Properties, and Parameters . . . 35
7.8. CALDAV:calendar-query REPORT . . . . . . . . . . . . . . . 36
7.8.1. Example: Partial Retrieval of Events by Time Range . . 38
7.8.2. Example: Partial Retrieval of Recurring Events . . . . 42
7.8.3. Example: Expanded Retrieval of Recurring Events . . . 45
7.8.4. Example: Partial Retrieval of Stored Free Busy
Components . . . . . . . . . . . . . . . . . . . . . . 48
7.8.5. Example: Retrieval of To-Dos by Alarm Time Range . . . 50
7.8.6. Example: Retrieval of Event by UID . . . . . . . . . . 51
7.8.7. Example: Retrieval of Events by PARTSTAT . . . . . . . 53
7.8.8. Example: Retrieval of Events Only . . . . . . . . . . 55
7.8.9. Example: Retrieval of All Pending To-Dos . . . . . . . 59
7.8.10. Example: Attempt to Query Unsupported Property . . . . 62
7.9. CALDAV:calendar-multiget REPORT . . . . . . . . . . . . . 63
7.9.1. Example: Successful CALDAV:calendar-multiget REPORT . 64
7.10. CALDAV:free-busy-query REPORT . . . . . . . . . . . . . . 66
7.10.1. Example: Successful CALDAV:free-busy-query REPORT . . 68
8. Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . 69
8.1. Client-to-Client Interoperability . . . . . . . . . . . . 69
8.2. Synchronization Operations . . . . . . . . . . . . . . . . 69
8.2.1. Use of Reports . . . . . . . . . . . . . . . . . . . . 69
8.2.1.1. Restrict the Time Range . . . . . . . . . . . . . 69
8.2.1.2. Synchronize by Time Range . . . . . . . . . . . . 70
8.2.1.3. Synchronization Process . . . . . . . . . . . . . 70
8.2.2. Restrict the Properties Returned . . . . . . . . . . . 72
8.3. Use of Locking . . . . . . . . . . . . . . . . . . . . . . 72
8.4. Finding Calendars . . . . . . . . . . . . . . . . . . . . 72
8.5. Storing and Using Attachments . . . . . . . . . . . . . . 74
8.5.1. Inline Attachments . . . . . . . . . . . . . . . . . . 74
8.5.2. External Attachments . . . . . . . . . . . . . . . . . 75
8.6. Storing and Using Alarms . . . . . . . . . . . . . . . . . 76
9. XML Element Definitions . . . . . . . . . . . . . . . . . . . 77
9.1. CALDAV:calendar XML Element . . . . . . . . . . . . . . . 77
9.2. CALDAV:mkcalendar XML Element . . . . . . . . . . . . . . 77
9.3. CALDAV:mkcalendar-response XML Element . . . . . . . . . . 78
9.4. CALDAV:supported-collation XML Element . . . . . . . . . . 78
9.5. CALDAV:calendar-query XML Element . . . . . . . . . . . . 78
9.6. CALDAV:calendar-data XML Element . . . . . . . . . . . . . 79
9.6.1. CALDAV:comp XML Element . . . . . . . . . . . . . . . 80
9.6.2. CALDAV:allcomp XML Element . . . . . . . . . . . . . . 81
9.6.3. CALDAV:allprop XML Element . . . . . . . . . . . . . . 81
9.6.4. CALDAV:prop XML Element . . . . . . . . . . . . . . . 82
9.6.5. CALDAV:expand XML Element . . . . . . . . . . . . . . 82
9.6.6. CALDAV:limit-recurrence-set XML Element . . . . . . . 83
9.6.7. CALDAV:limit-freebusy-set XML Element . . . . . . . . 84
9.7. CALDAV:filter XML Element . . . . . . . . . . . . . . . . 85
9.7.1. CALDAV:comp-filter XML Element . . . . . . . . . . . . 85
9.7.2. CALDAV:prop-filter XML Element . . . . . . . . . . . . 86
9.7.3. CALDAV:param-filter XML Element . . . . . . . . . . . 87
9.7.4. CALDAV:is-not-defined XML Element . . . . . . . . . . 88
9.7.5. CALDAV:text-match XML Element . . . . . . . . . . . . 88
9.8. CALDAV:timezone XML Element . . . . . . . . . . . . . . . 89
9.9. CALDAV:time-range XML Element . . . . . . . . . . . . . . 90
9.10. CALDAV:calendar-multiget XML Element . . . . . . . . . . . 94
9.11. CALDAV:free-busy-query XML Element . . . . . . . . . . . . 95
10. Internationalization Considerations . . . . . . . . . . . . . 95
11. Security Considerations . . . . . . . . . . . . . . . . . . . 95
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 96
12.1. Namespace Registration . . . . . . . . . . . . . . . . . . 96
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 96
14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 97
14.1. Normative References . . . . . . . . . . . . . . . . . . . 97
14.2. Informative References . . . . . . . . . . . . . . . . . . 98
Appendix A. CalDAV Method Privilege Table (Normative) . . . . . . 99
Appendix B. Calendar Collections Used in the Examples . . . . . . 99
1. Introduction
The concept of using HTTP [RFC2616] and WebDAV [RFC2518] as a basis for a calendar access protocol is by no means a new concept: it was discussed in the IETF CALSCH working group as early as 1997 or 1998. Several companies have implemented calendar access protocols using HTTP to upload and download iCalendar [RFC2445] objects, and using WebDAV to get listings of resources. However, those implementations do not interoperate because there are many small and big decisions to be made in how to model calendaring data as WebDAV resources, as well as how to implement required features that aren't already part of WebDAV. This document proposes a way to model calendar data in WebDAV, with additional features to make an interoperable calendar access protocol.1.1. Notational Conventions
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]. The term "protected" is used in the Conformance field of property definitions as defined in Section 1.4.2 of [RFC3253]. When XML element types in the namespaces "DAV:" and "urn:ietf:params:xml:ns:caldav" are referenced in this document outside of the context of an XML fragment, the string "DAV:" and "CALDAV:" will be prefixed to the element type names, respectively.1.2. XML Namespaces and Processing
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]. The namespace "urn:ietf:params:xml:ns:caldav" is reserved for the XML elements defined in this specification, its revisions, and related CalDAV specifications. XML elements defined by individual implementations MUST NOT use the "urn:ietf:params:xml:ns:caldav" namespace, and instead should use a namespace that they control. The XML declarations used in this document do not include namespace information. Thus, implementers must not use these declarations as the only way to create valid CalDAV properties or to validate CalDAV XML element types. Some of the declarations refer to XML elements defined by WebDAV [RFC2518], which use the "DAV:" namespace. Wherever such XML elements appear, they are explicitly prefixed with "DAV:" to avoid confusion.
Also note that some CalDAV XML element names are identical to WebDAV XML element names, though their namespace differs. Care must be taken not to confuse the two sets of names. Processing of XML by CalDAV clients and servers MUST follow the rules described in [RFC2518]; in particular, Section 14, and Appendix 3 of that specification.1.3. Method Preconditions and Postconditions
A "precondition" of a method describes the state of the server that must be true for that method to be performed. A "postcondition" of a method describes the state of the server that must be true after that method has been completed. If a method precondition or postcondition for a request is not satisfied, the response status of the request MUST either be 403 (Forbidden), if the request should not be repeated because it will always fail, or 409 (Conflict), if it is expected that the user might be able to resolve the conflict and resubmit the request. In order to allow better client handling of 403 and 409 responses, a distinct XML element type is associated with each method precondition and postcondition of a request. When a particular precondition is not satisfied or a particular postcondition cannot be achieved, the appropriate XML element MUST be returned as the child of a top-level DAV:error element in the response body, unless otherwise negotiated by the request.2. Requirements Overview
This section lists what functionality is required of a CalDAV server. To advertise support for CalDAV, a server: o MUST support iCalendar [RFC2445] as a media type for the calendar object resource format; o MUST support WebDAV Class 1 [RFC2518] (note that [rfc2518bis] describes clarifications to [RFC2518] that aid interoperability); o MUST support WebDAV ACL [RFC3744] with the additional privilege defined in Section 6.1 of this document; o MUST support transport over TLS [RFC2246] as defined in [RFC2818] (note that [RFC2246] has been obsoleted by [RFC4346]); o MUST support ETags [RFC2616] with additional requirements specified in Section 5.3.4 of this document;
o MUST support all calendaring reports defined in Section 7 of this document; and o MUST advertise support on all calendar collections and calendar object resources for the calendaring reports in the DAV:supported- report-set property, as defined in Versioning Extensions to WebDAV [RFC3253]. In addition, a server: o SHOULD support the MKCALENDAR method defined in Section 5.3.1 of this document.3. Calendaring Data Model
One of the features that has made WebDAV a successful protocol is its firm data model. This makes it a useful framework for other applications such as calendaring. This specification follows the same pattern by developing all features based on a well-described data model. As a brief overview, a CalDAV calendar is modeled as a WebDAV collection with a defined structure; each calendar collection contains a number of resources representing calendar objects as its direct child resource. Each resource representing a calendar object (event, to-do, journal entry, or other calendar components) is called a "calendar object resource". Each calendar object resource and each calendar collection can be individually locked and have individual WebDAV properties. Requirements derived from this model are provided in Section 4.1 and Section 4.2.3.1. Calendar Server
A CalDAV server is a calendaring-aware engine combined with a WebDAV repository. A WebDAV repository is a set of WebDAV collections, containing other WebDAV resources, within a unified URL namespace. For example, the repository "http://www.example.com/webdav/" may contain WebDAV collections and resources, all of which have URLs beginning with "http://www.example.com/webdav/". Note that the root URL, "http://www.example.com/", may not itself be a WebDAV repository (for example, if the WebDAV support is implemented through a servlet or other Web server extension). A WebDAV repository MAY include calendar data in some parts of its URL namespace, and non-calendaring data in other parts. A WebDAV repository can advertise itself as a CalDAV server if it supports the functionality defined in this specification at any point
within the root of the repository. That might mean that calendaring data is spread throughout the repository and mixed with non-calendar data in nearby collections (e.g., calendar data may be found in /home/lisa/calendars/ as well as in /home/bernard/calendars/, and non-calendar data in /home/lisa/contacts/). Or, it might mean that calendar data can be found only in certain sections of the repository (e.g., /calendar/). Calendaring features are only required in the repository sections that are or contain calendar object resources. Therefore, a repository confining calendar data to the /calendar/ collection would only need to support the CalDAV required features within that collection. The CalDAV server or repository is the canonical location for calendar data and state information. Clients may submit requests to change data or download data. Clients may store calendar objects offline and attempt to synchronize at a later time. However, clients MUST be prepared for calendar data on the server to change between the time of last synchronization and when attempting an update, as calendar collections may be shared and accessible via multiple clients. Entity tags and other features make this possible.3.2. Recurrence and the Data Model
Recurrence is an important part of the data model because it governs how many resources are expected to exist. This specification models a recurring calendar component and its recurrence exceptions as a single resource. In this model, recurrence rules, recurrence dates, exception rules, and exception dates are all part of the data in a single calendar object resource. This model avoids problems of limiting how many recurrence instances to store in the repository, how to keep recurrence instances in sync with the recurring calendar component, and how to link recurrence exceptions with the recurring calendar component. It also results in less data to synchronize between client and server, and makes it easier to make changes to all recurrence instances or to a recurrence rule. It makes it easier to create a recurring calendar component and to delete all recurrence instances. Clients are not forced to retrieve information about all recurrence instances of a recurring component. The CALDAV:calendar-query and CALDAV:calendar-multiget reports defined in this document allow clients to retrieve only recurrence instances that overlap a given time range.
4. Calendar Resources
4.1. Calendar Object Resources
Calendar object resources contained in calendar collections MUST NOT contain more than one type of calendar component (e.g., VEVENT, VTODO, VJOURNAL, VFREEBUSY, etc.) with the exception of VTIMEZONE components, which MUST be specified for each unique TZID parameter value specified in the iCalendar object. For instance, a calendar object resource can contain one VEVENT component and one VTIMEZONE component, but it cannot contain one VEVENT component and one VTODO component. Instead, the VEVENT and VTODO components would have to be stored in separate calendar object resources in the same collection. Calendar object resources contained in calendar collections MUST NOT specify the iCalendar METHOD property. The UID property value of the calendar components contained in a calendar object resource MUST be unique in the scope of the calendar collection in which they are stored. Calendar components in a calendar collection that have different UID property values MUST be stored in separate calendar object resources. Calendar components with the same UID property value, in a given calendar collection, MUST be contained in the same calendar object resource. This ensures that all components in a recurrence "set" are contained in the same calendar object resource. It is possible for a calendar object resource to just contain components that represent "overridden" instances (ones that modify the behavior of a regular instance, and thus include a RECURRENCE-ID property) without also including the "master" recurring component (the one that defines the recurrence "set" and does not contain any RECURRENCE-ID property).
For example, given the following iCalendar object: BEGIN:VCALENDAR PRODID:-//Example Corp.//CalDAV Client//EN VERSION:2.0 BEGIN:VEVENT UID:1@example.com SUMMARY:One-off Meeting DTSTAMP:20041210T183904Z DTSTART:20041207T120000Z DTEND:20041207T130000Z END:VEVENT BEGIN:VEVENT UID:2@example.com SUMMARY:Weekly Meeting DTSTAMP:20041210T183838Z DTSTART:20041206T120000Z DTEND:20041206T130000Z RRULE:FREQ=WEEKLY END:VEVENT BEGIN:VEVENT UID:2@example.com SUMMARY:Weekly Meeting RECURRENCE-ID:20041213T120000Z DTSTAMP:20041210T183838Z DTSTART:20041213T130000Z DTEND:20041213T140000Z END:VEVENT END:VCALENDAR The VEVENT component with the UID value "1@example.com" would be stored in its own calendar object resource. The two VEVENT components with the UID value "2@example.com", which represent a recurring event where one recurrence instance has been overridden, would be stored in the same calendar object resource.4.2. Calendar Collection
A calendar collection contains calendar object resources that represent calendar components within a calendar. A calendar collection is manifested to clients as a WebDAV resource collection identified by a URL. A calendar collection MUST report the DAV: collection and CALDAV:calendar XML elements in the value of the DAV: resourcetype property. The element type declaration for CALDAV: calendar is: <!ELEMENT calendar EMPTY>
A calendar collection can be created through provisioning (i.e., automatically created when a user's account is provisioned), or it can be created with the MKCALENDAR method (see Section 5.3.1). This method can be useful for a user to create additional calendars (e.g., soccer schedule) or for users to share a calendar (e.g., team events or conference rooms). However, note that this document doesn't define the purpose of extra calendar collections. Users must rely on non-standard cues to find out what a calendar collection is for, or use the CALDAV:calendar-description property defined in Section 5.2.1 to provide such a cue. The following restrictions are applied to the resources within a calendar collection: a. Calendar collections MUST only contain calendar object resources and collections that are not calendar collections, i.e., the only "top-level" non-collection resources allowed in a calendar collection are calendar object resources. This ensures that calendar clients do not have to deal with non-calendar data in a calendar collection, though they do have to distinguish between calendar object resources and collections when using standard WebDAV techniques to examine the contents of a collection. b. Collections contained in calendar collections MUST NOT contain calendar collections at any depth, i.e., "nesting" of calendar collections within other calendar collections at any depth is not allowed. This specification does not define how collections contained in a calendar collection are used or how they relate to any calendar object resources contained in the calendar collection. Multiple calendar collections MAY be children of the same collection.
(page 11 continued on part 2)