tech-invite   World Map     

3GPP     Specs     Glossaries     Architecture     IMS     UICC       IETF     RFCs     Groups     SIP     ABNFs       Search

RFC 4791

 Errata 
Proposed STD
Pages: 107
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: ~dav

Calendaring Extensions to WebDAV (CalDAV)

Part 1 of 5, p. 1 to 11
None       Next RFC Part

Updated by:    5689    6638    6764    7809    7953


Top       ToC       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       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       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       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       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       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       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       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       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       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       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 RFC Part