Tech-invite3GPPspaceIETFspace
96959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 4791

Calendaring Extensions to WebDAV (CalDAV)

Pages: 107
Proposed Standard
Errata
Updated by:  568966386764780979538996
Part 1 of 5 – Pages 1 to 11
None   None   Next

Top   ToC   RFC4791 - Page 1
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.
Top   ToC   RFC4791 - Page 2

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
Top   ToC   RFC4791 - Page 3
       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
Top   ToC   RFC4791 - Page 4
       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
Top   ToC   RFC4791 - Page 5

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.
Top   ToC   RFC4791 - Page 6
   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;
Top   ToC   RFC4791 - Page 7
   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
Top   ToC   RFC4791 - Page 8
   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.
Top   ToC   RFC4791 - Page 9

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).
Top   ToC   RFC4791 - Page 10
   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>
Top   ToC   RFC4791 - Page 11
   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)

Next Section