Network Working Group L. Dusseault
Internet-Draft Xythos
Expires: May 1, 2004 November 2003
Calendar Server Extensions for WebDAV (CalDAV)
draft-dusseault-caldav-00
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that other
groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at http://
www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on May 1, 2004.
Copyright Notice
Copyright (C) The Internet Society (2003). All Rights Reserved.
Abstract
In the five years since [WebDAV] was standardized, at least three
groups have used WebDAV as a basis to provide Internet calendar
access with a minimum of development effort. This draft explores the
reasons why this path might be chosen as well as the mechanisms that
might enable interoperable calendar access over WebDAV.
Dusseault Expires May 1, 2004 [Page 1]
Internet-Draft caldav November 2003
1. Introduction
1.1 Advantages of WebDAV for Calendar Access
WebDAV offers a number of advantages as a framework or basis for
calendar access. Most of these advantages boil down to a significant
reduction in design costs, implementation costs, interoperability
test costs, deployment costs, and the costs of mistakes. Every new
standard author or implementor finds certain small errors and the
IETF spends considerable time and effort remediating these. Some of
the advantages are contingent upon the way WebDAV is used, which is
why this section exploring advantages is inseparable from the rest of
this document for the moment.
This draft was commissioned at the Fall 2003 Minneapolis working
group meeting of the CalSched working group. The concept of using
HTTP/WebDAV as a basis for a calendaring server is by no means a new
concept: it was discussed in the CalSched working group as early as
1997 or 1998. Several companies have implemented calendaring servers
using HTTP PUT/GET to upload and download iCalendar events, and using
WebDAV PROPFIND 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 and properties, as well as how to implement required
features that aren't already part of WebDAV. This draft is therefore
intended as an exploration of the advantages of using WebDAV as well
as a proposal for one way to model calendaring data, and some ideas
for how to specify the features that go beyond WebDAV.
1.1.1 HTTP URLs for Calendar Objects
WebDAV is an extension of [HTTP], therefore its URLs are HTTP URLs.
If calendar access were an extension of WebDAV then it could also
share HTTP URLs. This can make a lot of sense because it allows very
simple calendar browsing clients to be written for devices that
already have a HTTP stack: the client merely needs to download those
calendar objects and be able to parse their formats. Since the
[iCal] formats are well-defined and well-supported, there's a natural
choice for what resource to download for a granular calendar object.
If HTTP GET can be used to represent a calendar object, then
appointment references can be easily downloaded, synchronized and
shared.
Specifying URLs is work. Not only are HTTP URLs appropriate for
Calendar objects, but they also eliminate the need to specify a new
URL schema and format and implement it.
Dusseault Expires May 1, 2004 [Page 2]
Internet-Draft caldav November 2003
1.1.2 Web Services and Web Interfaces
Calendar functionality is found extremely frequently on the Web. Even
calendaring systems designed primarily for access by smart clients
(smart clients are those which have application logic, as opposed to
thin clients or Web browsers) typically also have a Web interface
accessible by thin clients. Some calendaring applications are
available only via Web interfaces, for example those found on systems
such as Yahoo! Groups.
Because of the frequent use of Web interfaces, and the possibility of
supporting Web services, WebDAV is a particularly suitable framework
for calendar data. HTTP URLs to calendar objects can be used
natively in these systems. WebDAV provides property information in
an XML format, easily consumed by Web services which usually import
XML data anyway. Web interfaces can use stylesheets to transform XML
data into HTML presentation. This approach is described in <http://
www.microsoft.com/technet/prodtechnol/exchange/exchange2000/deploy/
confeat/e2kowa.asp>.
1.1.3 Client Implementations from Simple to Rich
The HTTP/WebDAV feature model encourages a wide range of clients,
from extremely simple to very rich. This is because servers must
support a wide range of features, but clients can pick and choose
which features to support. For example, even though a WebDAV server
must support the 'lockdiscovery' property, there's no requirement for
a client to request or parse this property value if it has no need
to. Generally speaking, clients may pick and choose which methods
and properties to support, as long as the client has a reasonable
response to the error conditions which might be returned. A simple
client can merely download and upload iCal objects and use very
little XML or advanced WebDAV functionality.
At the other end of the scale, a rich calendaring client using
WebDAV-based calendaring could choose to implement offline
functionality, free-busy searches crossing multiple servers, advanced
tasks and even some workflow, by using more of the features and
possibly defining its own dead properties. (Note: WebDAV's 'dead'
properties are those which the server allows clients to set but the
server has no special behavior regarding those properties. Other
clients may query and use these dead properties.)
1.1.4 Support for lock feature
WebDAV includes locking support. Locks are indispensible when
multiple authors may modify or create the same resources. Locks not
only prevent authors from accidentally overwriting each others work
Dusseault Expires May 1, 2004 [Page 3]
Internet-Draft caldav November 2003
(as ETags do), they also help authors coordinate that work by seeing
when to wait for another author to finish. Calendar users benefit
slightly from this functionality, more so when group calendars or
shared calendars allow booking of large groups of people or
broadly-used resources such as conference rooms or equipment.
1.1.5 Support for access control
The WebDAV ACL specification [ACL] was recently approved by the IESG.
However, several implementations have already shown interoperability
using this proposal. Any shared or group calendar application
benefits from interoperable access control. Access control can help
define who can schedule a user for new appointments without having to
make email requests, who can view free/busy time, and who can see the
details of certain appointments.
The IETF Security Area directors are concerned about a flaw in WebDAV
ACLs in that different servers can implement different sets of
privileges which can be hard for clients to handle. This can be
mitigated by a well-written spec for calendaring access via WebDAV,
by requiring servers advertising support for Calendaring features to
also support a specific and more well-defined set of privileges.
That approach is consistent with interoperating with existing WebDAV
clients.
As a general mechanism, WebDAV ACL may not always provide all the
power and specificity required by a calendar application. For
example, a calendaring application may wish to choose which other
users can view the start/end times of appointments, and separately
choose which users can also see the location of appointments.
However, as a standard and framework, WebDAV ACL provides a valuable
base from which to work. Furthermore, this proposal recommends that
advanced access control work for calendaring be relegated to another
document, so that standard calendaring systems can be built using
existing WebDAV ACL support.
1.1.6 Security, Implentations and Deployed Base
Many WebDAV client appliations, servers and APIs already exist.
WebDAV clients exist for modern Microsoft, Unix and Apple platforms.
Open source solutions are common and powerful. This can
significantly improve early interoperability and reduce development
and test time.
Much security integration work has already been done for WebDAV.
Today's Web and WebDAV servers all support TLS, providing at a
minimum single-hop privacy and server authentication. HTTP Digest
and Basic authentication may provide adequate client authentication
Dusseault Expires May 1, 2004 [Page 4]
Internet-Draft caldav November 2003
(Basic essentially uses a clear-text password but this may be
appropriate if the connection is secured with TLS). If not, work is
under way to support SASL with HTTP. As that work nears completion,
HTTP/WebDAV implementations will add SASL support so that work will
be done already for a calendaring system. It seems the HTTP/SASL work
is nearing last call (currently draft-nystrom-http-sasl-09.txt).
1.1.7 Migration, Synchronization and Offline Functionality
Synchronization and offline functionality are useful features in
Calendaring systems. Luckily, these are already well understood for
HTTP/WebDAV technology. HTTP ETags provide a reliable way to
determine whether a document in an offline cache needs to be
synchronized. At least two WebDAV clients supporting synchronization
have already been created: sitecopy (http://www.lyra.org/sitecopy/)
and Xythos WebFile Client (http://www.xythos.com/home/xythos/
wfc_features.html).
Many WebDAV working group members are discussing more work to improve
the performance of synchronization betweeen WebDAV clients and WebDAV
repositories. This ongoing work can benefit the calendaring
community at the same time, provided that the calendaring data model
fits easily in the WebDAV data model. The model proposed in this
document is one with which new WebDAV synchronization features are
likley to be equally applicable to calendaring data.
Data migration is almost the same problem as synchronization. One
use of a WebDAV tool like sitecopy is to move data to a new server.
The move is peformed by doing a new synchronization. Once the
initial synchronization is complete and verified, the data on the old
system can be removed or archived. Data portability is a convenient
feature to administrators, particularly when deploying a new system.
1.1.8 Search Support
Calendaring systems need a mix of fixed, specific searches (such as a
"search" for the events occuring today) and general search support.
WebDAV DASL can provide the functionality for the general search
support (although not always for specific frequently used searches).
The only hitch is that DASL is not yet standardized. The WebDAV WG
is currently putting effort into completing DASL and several
interoperable implementations already exist. In the meantime, if
DASL is delayed the specific fixed searches defined in this document
(using the REPORT method, see section 7), together with the ability
to browse calendars and request calendar objects with certain
property values, ought to provide quite reasonable calendar browse/
search support.
Dusseault Expires May 1, 2004 [Page 5]
Internet-Draft caldav November 2003
Note that the property promotion proposed in this document means that
not only can iCalendar documents be searched with "contains" text
searches, but also more sophisticated value matching can be done.
For example, since 'dtstart' is promoted from a VEVENT document body
to the resource's property list, a DASL search can be constructed to
find events with 'dtstart' before a specified date.
1.1.9 Clear extensibility model
WebDAV has a clear and proven extensibility model. The major way
functionality is extended is by defining new properties. Servers can
extend functionality by creating new live properties in custom
namespaces.
Clients can also extend functionality by creating new dead properties
in custom namespaces. For example, a client might wish to add a
"source-device" property in a custom namespace to record which device
created the calendar item. Dead properties are client-controlled
properties, where the namespace, name and value are entirely
controlled by the client. However, the server is required to store
these properties and return them, if requested, in PROPFIND queries
for individual resources or in listings of collection contents. Some
servers support text searching on all dead properties through the
DASL extensions. Dead properties can also be used in reports.
Other proven HTTP/WebDAV extensibility mechanisms include the ability
to define and advertise special WebDAV reports, new HTTP headers, and
for ultimate flexibility, new HTTP methods.
1.2 Required Calendaring Features Missing in WebDAV
Certain features that are required for modern enterprise-level
calendar systems are not present in HTTP or WebDAV, unsurprisingly.
This section makes clear what those missing features are. The rest
of this document is largely about how those missing features could be
filled in.
fanout One of the valuable functions a calendaring server can provide
to a client is fanning out scheduling requests. This allows
clients to perform simple operations (send a single schedule
request to the server) and have the server perform complex and
possibly time consuming processing. The server can send individual
scheduling requests to different invitees. It can choose the most
appropriate scheduling request transport for each invitee, not
necessarily using the same technology for each invitee to the same
meeting. The server can then remain online to collect and collate
responses. Fanout is unlike any existing WebDAV feature. Thus,
support for fanout dictates that a Calendaring server cannot
Dusseault Expires May 1, 2004 [Page 6]
Internet-Draft caldav November 2003
simply be an out-of-the-box WebDAV server with no modifications.
A CalDav server must have fanout logic in addition to its basic
WebDAV feature support. This document defines how fanout works.
recurrance Recurring appointments are common in calendaring
applications, and these are the hardest events to fit into a
finite resource listing model such as WebDAV. However, WebDAV
does have the functionality to perform reports. Recurrance
expansion is much like the expand-property report defined in
[DeltaV]. It seems pretty straightforward to define a CalDav
specific report to do recurrance expansion in the cases where it's
most useful.
notifications HTTP has no way for the server to contact the client.
HTTP interactions all begin with a client request and end with a
server response. The server has no obligation to maintain an open
connection to the client, rather the server MAY sever the TCP
connection after any response. Thus, there is no way for the
server to send the client alarms. Since HTTP is not designed for
this, it is recommended that a different technology be used to
solve this problem.
There are other IETF technologies much more suitable than HTTP to
provide notifications. Currently, SIP and XMPP are appropriate
technologies for servers to send notifications to subscribed
clients. The SIP SUBSCRIBE method defined in [REF - Roach RFC]
allows custom event types to be declared and subscribed to, and
CalDAV (or a separate draft) could define a list of types that
CalDAV servers could optionally (or be required to) support.
Similarly, XMPP allows clients to
Using a separate technology for notifications has advantages. It
can be seen as an advantage to have notification support optional,
at least for client implementations - a simple CalDav client need
not support notifications at all if it doesn't use alarms, or
generates its own alarms, or stays offline most of the time.
Another advantage is that it allows CalDAV servers to be
stateless, handling HTTP requests by generating responses, plus
events that can be fired off to a separate notification engine
(perhaps a separate server) and then forgotten. Finally, a
separate notification system can then deal with scaling to handle
the combinatorial problems of multiple subscribed clients (e.g. my
PDA, my laptop and my desktop) combined with multiple event
sources (e.g. my work calendar server plus my sports team calendar
server plus non-calendaring event sources).
Dusseault Expires May 1, 2004 [Page 7]
Internet-Draft caldav November 2003
It is likely that CalDAV servers will be required to support
notification once we have more input on which technology to use.
At the least, the server would support notification of new
resources added to collections, so that clients can subscribe to
know when new iTIP requests have been delivered or when other
clients have added new events or other calendaring objects. A
CalDAV server might also initiate notification when a reminder is
needed. This could allow simple non-calendaring clients (e.g. a
cell phone) to subscribe only to reminder event notifications
without having to do any other part of calendaring.
Dusseault Expires May 1, 2004 [Page 8]
Internet-Draft caldav November 2003
2. Required CalDAV features
This section lists what functionality is required of a CalDAV server.
To advertise support for CalDAV or claim compliance, a server:
o MUST support WebDAV Level 1 and 2 (all of RFC2518 including
locking).
o MUST support WebDAV ACL. See section (TODO) for more specifics on
how
o MAY support WebDAV DeltaV [DeltaV].
o MUST support DASL.
o MUST support HTTP/SASL.
o MUST support property promotion as described in this document.
o MUST support scheduling fanout as described in this document.
o MUST support calendaring REPORTs as described in this document.
Dusseault Expires May 1, 2004 [Page 9]
Internet-Draft caldav November 2003
3. Calendaring Data Model
One of the features which has made WebDAV a successful protocol is
its firm data model. This makes it a useful framework for other
applications such as calendaring. In this proposal, we attempt to
follow the same pattern by developing all new features based on a
well-described data model.
In this data model, every iCalendar VEVENT, VALARM, VJOURNAL, VTODO
and VFREEBUSY is stored as a regular HTTP/WebDAV resource. That
means each calendar resource may be individually locked and have
individual properties. These resources are sorted into WebDAV
collections with a mostly-fixed structure.
All resource types defined in this section, and all resources of MIME
type text/calendar appearing within these collections, have certain
required properties. These properties may be defined in this
document or in a separate document [TODO. Note: OSAF uses a
calendaring property model based on RDF calendaring and iCal that
could fit here]. Another TODO: This section needs more information
on what properties are REQUIRED on each type of collection. The iTIP
document has useful tables listing properties for each method, which
might apply to these collections.
3.1 Calendar Repository or Server
A CalDav repository, or 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://
example.org/webdav/" may contain WebDAV collections and resources,
all of which have URLs beginning with "http://example.org/webdav/".
Note that the root URL "http://example.org/" 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 areas, and
non-calendaring data in other areas. Calendar data will be indicated
through specific container relationships and resource types discussed
in the next sections.
A WebDAV repository may 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 (e.g. in /ldusseault/
calendar as well as in /nborenstein/calendar) or only in certain
sections of the repository (e.g. /caldav/usercals/*). Calendaring
features are only required in the repository sections that are or
Dusseault Expires May 1, 2004 [Page 10]
Internet-Draft caldav November 2003
contain calendaring objects. So a repository confining calendar data
to the /caldav/ collection would only need to support calendaring
REPORTs defined here within that collection.
The CalDAV server or repository is the canonical location for
calendar data, state information and semantics. The CalDAV server
has significant responsibility to ensure that the data is consistent
and compliant. Clients may submit requests to change data or
download data. Clients may store the calendar offline and attempt to
synchronize when reconnected, but changes to the repository occurring
in between are not considered to be automatically disposable and
clients should consider the repository to be the first authority on
state. HTTP Etags and other tools help this work.
3.2 Calendar Containers
A WebDAV collection which contains one or more calendars is
considered a Calendar Container. It has a new resource type:
<resourcetype xmlns="DAV">
<collection/>
<C:calendar-container xmlns:C="urn:ietf:params:xml:ns:calsch">
</resourcetype>
A calendar container may contain more than only Calendar resources.
However, non-Calendar resources within a Calendar-Container are not
typically intended for user display. These resources may contain
configuration or application data created by clients or offered by
the server for use by clients.
3.3 Calendars
A WebDAV collection which corresponds to a single calendar or VAGENDA
is a Calendar. It has a new resource type:
<resourcetype xmlns="DAV">
<collection/>
<C:calendar xmlns:C="urn:ietf:params:xml:ns:calsch">
</resourcetype>
The calendar collection contains sub-collections with specific kinds
of calendar objects. It also has certain properties which are
required to be present on calendards (see XML section).
Calendars MUST NOT contain other calendars. Calendars MAY exist
inside calendar-containers or inside normal WebDAV collections.
Thus, a repository may have calendars without having
calendar-containers. Calendar-containers are typically useful so
Dusseault Expires May 1, 2004 [Page 11]
Internet-Draft caldav November 2003
that a client can automatically detect when a user has multiple
calendars, e.g. "/ldusseault/calendars/work" and "/ldusseault/
calendars/karate".
A Calendar has a specified substructure. It MUST contain one event
collection and one alarm collection. It MAY contain one todo
collection and one journal. It MUST NOT contain more than one of any
of these specific collections, although it MAY contain additional
collections and non-collection resources of types not defined here.
3.4 Event Collection
Each Calendar MUST have a collection containing events. All
resources within this event collection (even within its
sub-collections) are considered part of the calendar, so substructure
can be used to organize events into smaller collections without
affecting the overall content of the calendar. The event collection
has its own resource type.
<resourcetype xmlns="DAV">
<collection/>
<C:events xmlns:C="urn:ietf:params:xml:ns:calsch">
</resourcetype>
Every non-collection resource in a calendar-events collection is
considered to be an event. Thus, listing the resources inside a
calendar-events collection is a good way to find out all the events
on a calendar. Each resource inside an events collection MUST have
the default MIME type text/calendar, and each one contains exactly
one VEVENT or VFREEBUSY object.
3.5 Alarm Collection
Each Calendar MUST have a collection containing alarms. All
resources within this alarm collection (even within its
sub-collections) are considered part of the calendar. The alarm
collection has its own resource type.
<resourcetype xmlns="DAV">
<collection/>
<C:alarms xmlns:C="urn:ietf:params:xml:ns:calsch">
</resourcetype>
Every non-collection resource in a alarms collection is considered to
be an alarm. Every resource MUST have the default MIME type text/
calendar, and contains exactly one VALARM.
Dusseault Expires May 1, 2004 [Page 12]
Internet-Draft caldav November 2003
3.6 Todo Collection
Each Calendar MAY have a collection containing tasks or todos. All
resources within this todo collection (even within its
sub-collections) are considered part of the calendar. The todo
collection has its own resource type.
<resourcetype xmlns="DAV">
<collection/>
<C:todos xmlns:C="urn:ietf:params:xml:ns:calsch">
</resourcetype>
Every non-collection resource in a todo collection is considered to
be a todo. Every resource MUST have the default MIME type text/
calendar, and contains exactly one VTODO.
3.7 Journal
Each Calendar MAY have a collection containing journal items. All
resources within this journal collection (even within its
sub-collections) are considered part of the journal. The journal
collection has its own resource type.
<resourcetype xmlns="DAV">
<collection/>
<C:journal xmlns:C="urn:ietf:params:xml:ns:calsch">
</resourcetype>
Every non-collection resource in a journal is considered to be a
journal item. Every resource MUST have the default MIME type text/
calendar, and contains exactly one VJOURNAL.
3.8 Invites Collection
Every Calendar-Container MUST have a child collection to contain
invites received through iTIP. If a Calendar is not inside a
Calendar-Container, then that Calendar MUST have its own invites
collection. This collection is to store received, accepted and
archived invitations so that clients can accept and review scheduling
invitations.
<resourcetype xmlns="DAV">
<collection/>
<C:invites xmlns:C="urn:ietf:params:xml:ns:calsch">
</resourcetype>
Every non-collection resource in the invites collection is considered
to be a REQUEST. Every resource MUST have the default MIME type
Dusseault Expires May 1, 2004 [Page 13]
Internet-Draft caldav November 2003
text/calendar, and contains exactly one REQUEST.
3.9 Scheduling Collection
Every Calendar MUST have a child collection to contain fanout
requests and responses for appointments scheduled by the calendar
owner (or other users of this calendar). This collection is to store
REQUESTs initiated by this calendar server for this calendar, as well
as REPLY items received in reply. This collection is only for review
because the CalDAV server is responsible for parsing incoming REPLY
messages and adding attendee information to events.
<resourcetype xmlns="DAV">
<collection/>
<C:scheduling xmlns:C="urn:ietf:params:xml:ns:calsch">
</resourcetype>
Every non-collection resource in the invites collection is considered
to be a REQUEST or REPLY. Every resource MUST have the default MIME
type text/calendar, and contains exactly one REQUEST or exactly one
REPLY.
3.10 Recurrance and the Data Model
Recurrance is an important part of the data model because it governs
how many resources are expected to exist.
Consider the outcome if recurrance were handled through the creation
of many nearly-identical WebDAV resources. With this model, it
becomes hard to keep their data consistent. Even worse, some
features like LOCK become difficult -- it's hard to lock the right
set of resources so that the user can change the title of all
recurrances of an appointment. With these considerations, this
proposal does not treat recurrances as separate resources.
Instead, this proposal models recurrance patterns as properties of
event resources. This makes for much less data to synchronize, and
makes it easier to make changes to all recurrances or to a recurrance
pattern. It makes it easier to create a recurring event, and easier
to delete all recurrances.
The drawback of the recurrance-is-a-property approach is that it
becomes harder to see what events occur in a given time period. It's
a very common function for calendar views to display all events
happening between midnight yesterday and midnight tonight, or all
events happening within one week. In these views, each recurrance
appears as if it were an individual appointment. To make these views
possible, this proposal defines a REPORT specifically to view events
Dusseault Expires May 1, 2004 [Page 14]
Internet-Draft caldav November 2003
in a time period [TODO - ref section].
Because of this choice, clients MUST NOT create separate resources to
represent a recurring event when the recurrance pattern is known.
Otherwise, it makes it more difficult for other clients to
interoperate and modify the recurring event. Most importantly,
clients MUST NOT duplicate events represented through recurrance
patterns with manually created events, which would appear as
duplicates to the server and to other clients.
3.11 Calendar, event and custom timezones
This is a big issue because CalDAV servers need to know the timezone
of the calendar in order to calculate recurrances in a deterministic
manner. In addition to having a calendar default timezone,
individual events (e.g. those received in a scheduling request from
another place) can have different timezones. Finally, iCalendar has
a way to specify custom timezones.
The default calendar timezone is probably simply a property value on
the calendar collection, which the calendaring client can change. The
event timezone is a piece of VEVENT metadata that would therefore
appear both inside the event in iCalendar format, and as a promoted
property on the event resource. Storing custom timezone definitions
can be through a new collection if necessary. More discussion here
is welcome.
3.12 Creating Resources
Calendars, calendar-containers, collections of calendar objects, and
individual calendar objects may all be created by either the CalDAV
client or by the CalDAV server. For example, a server might come
preconfigured with a user's calendar collection, or the CalDAV client
might create a new calendar collection. Servers might create event
requests as calendar objects inside a VEVENT collection, or clients
might create event requests. Either way, both client and server MUST
comply with the requirements in this document, and MUST understand
objects appearing in calendars or calendar-containers according to
the data model defined here.
When servers create HTTP resources, it's not hard for the server to
choose a unique URL. It's slightly tougher for clients, because a
client might not want to examine all resources in the collection, and
might not want to lock the entire collection to ensure that a new one
isn't created with a name collision. However, there are tools to
mitigate this. If the client intends to create a new non-collection
resource, such as a new VEVENT, the client SHOULD use the HTTP header
"If-None-Match: *" on the PUT request. The Request-URI on the PUT
Dusseault Expires May 1, 2004 [Page 15]
Internet-Draft caldav November 2003
request MUST include the target collection, where the resource is to
be created, plus the name of the resource in the last path segment.
The last path segment could be a random number, or it could be a
sequence number, or a string related to the object's 'summary'
property. No matter how the name is chosen, the "If-None-Match"
header ensures that the client cannot overwrite an existing resource
even if it has accidentally chosen a duplicate resource name.
PUT /lisa/calendar/events/mtg10028.ics HTTP/1.1
If-None-Match: *
Host: cal.example.com
Content-Type: text/icalendar
Content-Length: XXX
BEGIN:VEVENT
DTSTART:20010714T170000Z
DTEND:20010715T035959Z
SUMMARY:Bastille Day Party
END:VEVENT
The request to change an existing event is the same, but with a
specific ETag in the "If-Match" header, rather than the
"If-None-Match" header.
For optimum interoperability with existing HTTP clients, CalDAV
clients and servers MUST use the file extension ".ics" as well as the
"text/ icalendar" MIME type, whenever creating Calendar objects of
that MIME type.
Note because of these requirements that there is no semantic value in
any other part of a resource name other the file extension. Thus, a
Calendar collection may be called "calendar", "cal", "Calendario" or
"日历" (Chinese). It's the properties of the resource that define
what it is, not the name.
3.13 Users and Groups
The WebDAV ACL specification requires that any principal to whom
permissions can be represented via a WebDAV resource (complete with
WebDAV properties and a HTTP URL). Thus, both users may be
represented (for example, as /principals/users/ldusseault) and groups
(for example, as /principals/groups/calsch). This feature offers an
excellent framework for linking users to calendars in a fashion not
otherwise easily implemented.
Note that the WebDAV principal resources may not be modifiable
through WebDAV. This is an important consideration because it allows
the principal directory to be merely a WebDAV representation of data
Dusseault Expires May 1, 2004 [Page 16]
Internet-Draft caldav November 2003
which is canonically stored in an outside system. For example, an
enterprise might use an LDAP server to store and administer all user
and group properties. This LDAP server could be linked into the
WebDAV repository through configuration information. WebDAV server
implementations exist which offer principal resources, but when the
principal resources are queried the server actually makes a LDAP
request to get the principal information from its official source.
This saves WebDAV clients from having to implement LDAP and provides
a single URL format for principals regardless of whether the user
directory is stored in LDAP or some other system.
A server supporting CalDAV MUST support additional properties on
principal resources if these principals are associated with
calendars. In addition, certain properties are required on calendars
to link to principal resources. These properties are defined in the
properties section.
Dusseault Expires May 1, 2004 [Page 17]
Internet-Draft caldav November 2003
4. Property Promotion and Demotion
Property promotion and demotion (hereafter called simply "property
promotion" is the name for the functionality by which a server
ensures that a resource's internal data and its externally-visible
metadata remain consistent. In WebDAV, a collection listing
(PROPFIND) selects a set of property names to retrieve. For a
collection listing to be useful to browse calendars, certain
calendaring information must be exposed as WebDAV properties (this
also makes WebDAV SEARCH useful, and makes the definition of REPORTs
easier). Since a calendar resource of type text/calendar has
properties which duplicate some of its internal state, it's the
server's responsibility to keep those consistent somehow.
The server has some leeway in how it makes properties and bodies
consistent, as long as the response to a GET shows information
consistent with the response to a PROPFIND in the interval in which a
calendar object has not been altered. Thus, the server MAY change
property values when a PUT is performed that alters data exposed as
properties, and also change the body when a PROPPATCH is performed
that alters calendar properties. Alternatively, a server could
implement "lazy promotion" and apply consistency changes only when a
GET, PROPFIND, SEARCH or REPORT is issued. Finally, a server might
decompose property data and non-property data into separate locations
and recompose the information only when a GET requests the entire
resource. Any of these approaches MUST be transparent to the client,
in that operations behave consistently, with complete round-trip
fidelity of all the data originally provided. Thus, a server MAY
canonicalize its resource bodies (e.g. eliminate meaningless spaces)
but MUST preserve all data.
This section needs further definition and details. Clients can
upload iCalendar files with syntactic or semantic errors, so helpful
error codes must be chosen. Also, this draft needs to define what to
do with 'x-' custom elements inside these uploaded files.
Dusseault Expires May 1, 2004 [Page 18]
Internet-Draft caldav November 2003
5. Scheduling and Fanout
Scheduling and fanout is a valuable function provided by advanced
calendaring servers. Simple clients clearly benefit from having the
logic handled by the server. Rich clients also benefit from having
to upload less data to various servers (including messaging servers
to send invitations via messages) to accomplish the same things.
Servers can sometimes provide more advanced scheduling functionality
than clients - for example, a server providing fanout could create
"unconfirmed" VEVENT resources within invitees' calendars.
However, rich calendaring clients may prefer to do fanout. Clients
can perform special functionality during scheduling (for example, a
client may be configured to be able to directly put events on others'
calendars if the user has sufficient permissions). Thus, it is
proposed that CalDAV allow the client to either perform fanout and
merely create the event (complete with attendee information) OR
request that the server perform fanout. In other words, the server
MUST handle fanout if requested, and clients MAY perform fanout if
the client chooses.
CalDAV servers MUST support iTIP to do fanout when requested, and
MUST fall back to iMIP when iTIP is impossible. Each REQUEST
generated on behalf of a Calendar MUST be stored in the calendar's
'scheduling' collection. Each REPLY received to those REQUESTs MUST
be stored in the same collection. These REQUEST and REPLY items are
available until the client deletes them so that clients can view
extra information (if present). CalDAV servers MUST parse incoming
REPLY messages and update the appropriate event with attendee
information. Thus, it's not necessary for clients to review REQUEST
or REPLY items, although they may.
As well, CalDAV servers MUST support iTIP to receive scheduling
requests. When a CalDAV server receives an iTIP request, it MUST
store the REQUEST object in an "invites" collection for the client to
handle. Each invite resource will have properties indicating whether
it is new, has been accepted, has been rejected, and whether it is an
obsolete REQUEST (the event has passed). Note that when a calendar
server receives iTIP requests it MAY auto-accept based on user
configured preferences. How these preferences are configured is out
of the scope of this specification, but one could imagine that a
CalDAV server could host auto-accept configuration Web pages. A
CalDAV server is NOT REQUIRED to do any auto-accepting, it MAY simply
store the requests for the next time the client is online.
Exact mechanisms for triggering fanout requests must be determined
and input is welcome. There are several ways fanout could be
accomplished: (a) A PUT of the resource triggers fanout, so the body
Dusseault Expires May 1, 2004 [Page 19]
Internet-Draft caldav November 2003
must contain the fanout information (text and flags), (b) a PROPPATCH
triggers fanout if certain properties are set, (c) a new method
requests fanout of a resource that has already been uploaded. These
three approaches are the most obvious to this author and there is
surprisingly little to choose between. More input is needed, for
example input on whether the fanout should be synchronous or
asynchronous. An asynchronous fanout mechanism using PUT or
PROPPATCH would mean that the client would synchronously handle the
PUT or PROPPATCH itself, but send invitations at some later time. A
synchronous fanout mechanism would probably use a new method with a
name like INVITE, because adding new synchronous behavior to existing
methods might require more complicated server implementation work.
When the server does fanout, it may send requests and receive
replies. Probably these requests and responses should be stored as
WebDAV resources so that the client can examine the details if
desired. This could be a separate collection within the calendar
collection.
Dusseault Expires May 1, 2004 [Page 20]
Internet-Draft caldav November 2003
6. CalDAV Resource Properties
The namespace "urn:ietf:params:xml:ns:calsch" is reserved for
specifications written by the CalSched working group or its eventual
successors. It MUST NOT be used for custom extensions. It is the
namespace for every new defined in this section (and every XML
element defined in this document).
The W3C RDF Calendar group has already defined a namespace and XML
element names for many calendaring properties, and these are
completely consistent with iCal [RDF-ICAL]. This standard reuses
those namespaces, names and definitions. Additional properties are
needed to describe calendars and calendar-containers, because the W3C
RDF Calendar group defines properties for the iCalendar-defined
objects only. The properties that are defined by the RDF Calendar
group are not redefined in this section.
Note that the XML Schema declarations used in this document are
incomplete, in that they do not include namespace information. Thus,
the reader MUST NOT use these declarations as the only way to create
valid CalDAV properties or to validate CalDAV-related XML. Some of
the declarations refer to XML elements defined by WebDAV which use
the "DAV:" namespace. Those WebDAV elements are not redefined in
this document.
6.1 Required Properties: VEVENT
TODO: Has the RDF Calendar group, or iCal, already done the work of
defining which properties MUST exist on a VEVENT object? This should
just be reused.
Required properties probably include:
In the 'http://www.w3.org/2002/12/cal/ical' namespace:
dtstart dtend or duration...
TODO - perhaps a separate document on
6.2 Calendar-owner Property
Name: calendar-owner
Location: MUST appear on a calendar or calendar-container if there is
a principal resources (user or group) with which it is associated.
Purpose: This property is used to discover the calendar owner, or the
person or group for which the calendar events are scheduled. It
MAY have the same value as the DAV (ACL) 'owner' property, but not
Dusseault Expires May 1, 2004 [Page 21]
Internet-Draft caldav November 2003
necessarily. For example, the president may be the
calendar-owner, but her secretary is the owner for all ACL/
administrative purposes. This property contains one 'href' element
in the "DAV:" namespace.
Declaration: <!ELEMENT calendar-owner (href) >
Extensibility: MAY contain additional elements, which MUST be ignored
if not understood.
6.3 Calendars Property
Name: calendars
Location: MUST appear on ACL Principal resources with which a
calendar is associated.
Purpose: This property is used to browse principals and find out what
calendars they have, for the purpose of then browsing their
calendar or their free/busy published information. It contains
one or more 'href' elements in the "DAV:" namespace (this is a
normal WebDAV approach to putting one or more URL value in a
property value).
Declaration: <!ELEMENT calendars (href+) >
Extensibility: MAY contain additional elements, which MUST be ignored
if not understood.
Dusseault Expires May 1, 2004 [Page 22]
Internet-Draft caldav November 2003
7. Calendaring Reports
This section defines the reports which a CalDAV server MUST support.
These all provide special query functionality not normally handled by
the generic PROPFIND or SEARCH mechanisms. This can be required when
a PROPFIND or SEARCH cannot be written to request the data required
for a common use case without an reasonable amount of complex
calculation or unnecessary data transmitted. See DeltaV or ACL
standards for some examples of reports required in other situations.
As defined in DeltaV, all REPORT requests include an XML body naming
the type of report requested (only one) and some variables for how
that report is to be compiled. Note that support for the REPORT
method does not imply support for all reports defined in all WebDAV
extensions. A CalDAV server is required to support all the reports
defined here and in the ACL standard, but is not expected to support
DeltaV reports unless it advertises them. Reports are advertised with
the 'supported-report-set' property defined in DeltaV (again, even if
versioning-specific features are not at all supported).
Each report defined here comes with specialized errors. In addition,
some WebDAV status codes are applicable to any request or to any
REPORT request. This includes redirect status codes, syntax errors
(400 Bad Request), permission errors or policy errors (401
Unauthorized and 403 Forbidden), 404 Not Found, or a request-body
that isn't XML or is invalid XML (422 Unprocessable Entity). When an
error is defined in this document, it is used in an error response
body inside an XML document (this practice was established with
DeltaV and ACL in order to avoid status code collisions). For
example:
Sample error response
HTTP/1.1 409 Conflict
Date: Sun, 16 November 2003 18:40:01 GMT
Content-Type: text/xml; charset="utf-8"
Content-Length: XXX
<?xml version="1.0" encoding="UTF-8" ?>
<D:error xmlns:D="DAV:">
<range-invalid xnlns="urn:ietf:params:xml:ns:calsch"/>
</D:error>
7.1 The 'calendar-time-range' report
The 'calendar-time-range' report returns all objects of a specific
Dusseault Expires May 1, 2004 [Page 23]
Internet-Draft caldav November 2003
type within a time range, with or without recurrance expanded. The
first use case for this report is to have the server expand recurring
events to make a calendar view of a day's or week's events easy. The
WebDAV PROPFIND and SEARCH syntaxes do not as easily support this use
case. Even when the client doesn't need recurrance expanded, it can
use this report to save itself from the need to write a SEARCH query
which catches all events overlapping any part of the period
requested, or from having to do a PROPFIND and filter itself.
The second use case for this report is for users other than the
calendar owner to find out when the calendar owner is free. This is
only a minor variation, because it's effectively the same objects
(VEVENT and VFREEBUSY), only with permissions restricting the kind of
data the server will return. Servers MUST allow users with
permission to view the free-busy times for a calendar to use this
report. Servers MUST return event properties for visible events
including dtstart, dtend and free-busy type. Other properties MAY be
refused.
The third use case for this report is to list all alarms in a time
range. The selection of VALARM objects, instead of VEVENT or
VFREEBUSY objects, allows this use case to be handled with the same
report framework.
7.1.1 Request for 'calendar-time-range'
The REPORT request-body MUST have the root element
'calendar-time-range'.
o The root element MAY contain the 'expand-recurrances' element as a
flag.
o The root element MAY contain the 'object-types' element to list
what object types to return.
o The root element MUST contain the 'prop' element in the "DAV:"
namespace as defined in WebDAV, to list what property values to
return.
o The root element MUST contain one 'dtstart' element
o The root element MUST contain one 'dtend' element.
The Request-URI for this report MUST be a Calendar-container, a
calendar collection, or an events collection. The server MUST
collation all the event data contained within the requested
collection.
Dusseault Expires May 1, 2004 [Page 24]
Internet-Draft caldav November 2003
Sample request for 'time-range-events' report
REPORT /lisa/Calendar HTTP/1.1
Host: cal.example.com
Content-Type: text/xml
Content-Length: XXX
<?xml version="1.0>
<report xmlns="DAV:" xmlns:i="http://www.w3.org/2002/12/cal/ical">
<c:time-range-events xmlns:c="urn:ietf:params:xml:ns:calsch">
<i:dtstart>20031101</i:dtstart>
<i:dtend>20031131</i:dtend>
<c:object-types><i:Vevent/></c:object-types>
<prop>
<i:dtstart/> <i:dtend/> <i:summary/> <i:valarm/>
</prop>
</c:expand-event-report>
</report>
7.1.2 Response to 'time-range-events'
The response to this report is a WebDAV Multi-Status response,
containing one <response> element for each event AND for each
recurrance. This differs from the PROPFIND response to an event
collection only in that the relevant recurrances each have their own
<response> element, not just the master event.
The server MUST expand all recurring events within the entire
collection (including sub-collections) if requested, and return all
those events or recurrances which overlap the period defined by the
start to end. If an event ends at precisely the requested start
time, or begins at precisely the requested end time, it does not
overlap the period requested.
If the user requests properties which may not be seen (e.g. a user
with permission only to see free-busy time requests to see the
location of events), the response uses the regular WebDAV approach
for properties which are private (either 401 Unauthorized if the
client is not authenticated, or 403 Forbidden if the client is
authenticated and still the property value is private). These errors
appear within the standard Multi-Status response.
TODO: I guess an example is probably needed here.
7.1.3 Errors for 'time-range-events'
Dusseault Expires May 1, 2004 [Page 25]
Internet-Draft caldav November 2003
invalid-range The server returns this error when the range requested
in the 'dtstart' and 'dtend' values is an invalid range (e.g.
dtend is earlier than or equal to dtstart value).
7.1.4 Timezones report
CAP offers a way to get timezones. I'm unclear whether this is a
server-wide list, or whether the contents vary by calendar/user.
That would help to decide whether to use a special OPTIONS request, a
new REPORT, or a new collection.
Dusseault Expires May 1, 2004 [Page 26]
Internet-Draft caldav November 2003
8. Using existing WebDAV features in Calendaring
8.1 SEARCH and calendar data
The DASL framework for search requests provides a powerful way to
find calendars in a repository, and to find calendar objects within a
calendar. It is virtually unlimited in variations. It can be used
to request and search on calendar properties as well as WebDAV
properties. One drawback of DASL, however, is that implementations
are given great leeway in which properties support search. That's
less acceptable in calendaring applications, so this specification
adds requirements of CalDAV servers to support searches on specific
properties.
CalDAV servers MUST support 'eq' DASL searches on the following
properties: uid, valarm.
CalDAV servers MUST support 'eq', 'gt' and 'lt' DASL searches on the
following properties: dtstart, dtend, dtstamp.
CalDAV servers MUST support 'eq' and 'contains' DASL searches on the
following properties: location, comment, description, summary,
organizer, attendee, categories.
8.2 Disconnected Operations
WebDAV already provides functionality required to synchronize a
collection or set of collections, make changes offline, and a simple
way to resolve conflicts when reconnected. Strong ETags are the key
to making this work, but these are not required of all WebDAV
servers. Since offline functionality is more important to Calendar
applications than to other WebDAV applications, CalDAV servers MUST
support strong ETags.
Much more work could be done to make disconnected operations work
better. WebDAV implementors have discussed ETag-like tags for
collections (CTags?) which would change whenever the membership (or
members?) of a collection changed. Tombstones might also be useful
to synchronize with DELETE operations. However, all these mechanisms
are of general use and not limited to Calendaring. Therefore, it is
suggested that work on advanced synchronization take place in a
separate document independent of the calendaring-specific features
discussed here. Many people are interested in doing this kind of
work and it has wide applicability and usefulness. Requirements or
design contributions from calendaring implementors are welcome.
TODO: this section should be expanded to give more guidance to
clients on how to synchronize WebDAV objects most effectively. In
Dusseault Expires May 1, 2004 [Page 27]
Internet-Draft caldav November 2003
particular, we need to understand how UID/SEQ metadata works with
synchronization.
Note that recurrance isn't a synchronization problem in this model.
Recurring items appear only once in normal PROPFIND responses, so
there's no danger that in synchronizing a client will accidentally
create extra recurrances. Instead, recurrances appear only in a
special REPORT which MUST not be used for synchronization. We
believe this separation between data (recurring appointments) and
presentation (the display of a period containing several recurrances)
is crucial to simplifying synchronization.
Dusseault Expires May 1, 2004 [Page 28]
Internet-Draft caldav November 2003
References
[1] Goland, Y., Whitehead, E., Faizi, A., Carter, S. and D. Jensen,
"HTTP Extensions for Distributed Authoring - WebDAV", RFC 2518.
[2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L.,
Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
HTTP/1.1", June 1999.
[3] Dawson, F. and D. Stenerson, "Internet Calendaring and
Scheduling Core Object Specification (iCalendar)", RFC 2445.
[4] "iCal Schema in RDF/XML", site http://www.w3.org/2002/12/cal/.
[5] Mogul, J., Krishnamurthy, B., Douglis, F., Feldmann, A., Goland,
Y., van Hoff, A. and D. Hellerstein, "Delta encoding in HTTP",
RFC 3229, January 2002.
Author's Address
Lisa Dusseault
Xythos Software, Inc.
2064 Edgewood Dr.
Palo Alto, CA 94303
US
EMail: lisa@xythos.com
Dusseault Expires May 1, 2004 [Page 29]
Internet-Draft caldav November 2003
Appendix A. Acknowledgements
Cyrus Daboo and Michael Arick have provided substantial feedback for
this draft.
Dusseault Expires May 1, 2004 [Page 30]
Internet-Draft caldav November 2003
Appendix B. Changes
Dusseault Expires May 1, 2004 [Page 31]
Internet-Draft caldav November 2003
Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; neither does it represent that it
has made any effort to identify any such rights. Information on the
IETF's procedures with respect to rights in standards-track and
standards-related documentation can be found in BCP-11. Copies of
claims of rights made available for publication and any assurances of
licenses to be made available, or the result of an attempt made to
obtain a general license or permission for the use of such
proprietary rights by implementors or users of this specification can
be obtained from the IETF Secretariat.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights which may cover technology that may be required to practice
this standard. Please address the information to the IETF Executive
Director.
Full Copyright Statement
Copyright (C) The Internet Society (2003). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assignees.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
Dusseault Expires May 1, 2004 [Page 32]
Internet-Draft caldav November 2003
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgment
Funding for the RFC Editor function is currently provided by the
Internet Society.
Dusseault Expires May 1, 2004 [Page 33]
