|Network Working Group||C. Daboo|
|Intended status: Informational||B. Desruisseaux|
|Expires: June 16, 2005||Oracle|
|December 13, 2004|
Calendaring and Scheduling Extensions to WebDAV (CalDAV)
Note: a later version of this document has been published as RFC4791.
This document is an Internet-Draft and is subject to all provisions of section 3 of RFC 3667. By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she become aware will be disclosed, in accordance with RFC 3668.
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 June 16, 2005.
Copyright © The Internet Society (2004). All Rights Reserved.
This document specifies a set of methods, headers and resource types that define the calendaring and scheduling extension to the WebDAV protocol. The new protocol elements are intended to make WebDAV-based calendaring an intereropable standard that supports single-user calendar access, calendar sharing, and calendar publishing.
The concept of using HTTP  and WebDAV as a basis for a calendaring server 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 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 to propose a standard way of modeling calendar data in WebDAV, plus some additional features to make calendaring work well.
WebDAV properties and other XML element names defined in this specification all use the "urn:ietf:params:xml:ns:caldav" namespace. Implementors may find occasion to define new WebDAV properties and other XML elements in implementing this specification, but this namespace is not intended for use in custom extensions.
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 cost 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.
WebDAV is an extension to the HTTP/1.1  protocol, 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 iCalendar  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 new URL formats creates additional work for implementors of clients, servers and related applications that might see those URLs. Although new URL formats are appropriate in many cases, sometimes HTTP URLs may be appropriate -- particularly for an application which extends HTTP and allows all the standard HTTP methods to work correctly. 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.
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>.
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 iCalendar 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.)
WebDAV includes locking support. Locks are indispensable when multiple authors may modify or create the same resources. Locks not only prevent authors from accidentally overwriting each others work (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.
The WebDAV ACL specification  is now a standard, and several implementations have already demonstrated interoperability. 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.
WebDAV ACLs provide a flexible and extensible list of privileges, which is both good and bad for calendaring. It's good because it allows a calendaring-over-WebDAV standard to define additional privileges that may not be used in normal WebDAV use cases (for example, the privilege to view a calendar's free-busy information). However the bad part is that a flexible and extensible list of privileges is hard for clients to display and explain to users. This draft attempts to minimize the difficulty by more closely defining the list of privileges that a CalDAV server must support, including calendaring-specific privileges.
Implementors should note that WebDAV ACLs are not designed to limit access to specific properties. 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.
Many WebDAV client applications, 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 (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).
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 between 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 likely 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 performed 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.
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 (a work in progress) [TODO: REF]. 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.
This section lists what functionality is required of a CalDAV server. To advertise support for the 'calendar-access' features of CalDAV, a server:
To advertise support for the 'calendar-schedule' features of CalDAV, a server:
In addition, a server:
If the server supports the calendar access features described in this document it MUST include "calendar-access" as a field in the DAV response header from an OPTIONS request on any resource that supports any calendar properties, reports, or privileges.
If the server supports the calendar scheduling features described in this document it MUST include "calendar-schedule" as a field in the DAV response header from an OPTIONS request on any resource that supports the SCHEDULE method.
>> Request <<
OPTIONS /lisa/calendar/outbox/ HTTP/1.1 Host: cal.example.com
>> Response <<
HTTP/1.1 200 OK Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE Allow: MKCOL, PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, SCHEDULE DAV: 1, 2, calendar-access, calendar-schedule Content-Length: 0
In this example, the OPTIONS response indicates that the server supports both calendar access and scheduling functionality and that /lisa/calendar/outbox/ can be specified as a Request-URI to the SCHEDULE method.
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 the CalDAV data model, every iCalendar VEVENT, 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.
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 and mixed with non-calendar data in nearby collections (e.g. calendar data may be found in /lisa/calendar/ as well as in /nborenstein/calendar/, and non-calendar data in /lisa/contacts/). Or, it might mean that calendar data can be found only in certain sections of the repository (e.g. /caldav/usercals/*). Calendaring features are only required in the repository sections that are or contain calendaring objects. So a repository confining calendar data to the /caldav/ 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, 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.
Recurrence is an important part of the data model because it governs how many resources are expected to exist.
Consider the outcome if recurrence were handled through the creation of many nearly-identical WebDAV resources. With this model, it becomes hard to keep synchronized 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 recurrences of an appointment. Due to these considerations, this proposal does not model recurrences as separate resources.
Instead, this proposal models recurrence patterns as properties of event resources. This makes for much less data to synchronize, and makes it easier to make changes to all recurrences or to a recurrence pattern. It makes it easier to create a recurring event, and easier to delete all recurrences.
The drawback of the recurrence-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 recurrence appears as if it were an individual appointment. To make these views possible, this proposal defines a REPORT specifically to view events in a time period [TODO - ref section].
Because of this choice, clients MUST NOT create separate resources to represent a recurring event when the recurrence 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 recurrence patterns with manually created events, which would appear as duplicates to the server and to other clients.
One of the key workflows in calendaring and scheduling is when a meeting organizer creates an invitation and sends it to a number of attendees. Each of those attendees wants the event to appear on their own calendar (if they accept it) and have their status reflected back to the organizer. This section is a brief overview of how this workflow relates to the data model of CalDAV, which only applies if the server supports the 'calendar-schedule' set of features.
An invitation is not yet an accepted event. Thus, invitations should appear outside the main part of the calendar, and not be included in free-busy rollup or calendar REPORT requests. To handle this in the data model, CalDAV defines an iTIP Inbox collection to contain incoming invitations. Similarly, the Inbox folder can handle incoming replies and other iTIP methods. The Inbox contains inbound iTIP messages long after they are handled/seen by the user, because this serves as a track record and to help synchronize between multiple clients.
Outbound iTIP messages are very similar, and need to be tracked both to help synchronize between multiple clients and to support delegation use cases. CalDAV defines an iTIP Outbox collection to contain outbound invitations and other iTIP methods. A single user with multiple clients can use this collection to synchronize the outbound request history. Two users coordinating scheduling with one calendar (e.g. a calendar user and her assistant) can see what scheduling messages the other user has sent. (The calendar owner would then typically have permission to DELETE the scheduling messages but the assistant need not.)
Thus, for every scheduling request, we would like to see one copy in the organizer's iTIP Outbox, as well as one copy in each attendee's iTIP Inbox. Rather than require that many PUT requests, CalDAV defines the SCHEDULE method to request that the server place a copy of an iTIP message in a given iTIP Outbox, and do its best to fan out the iTIP message to the recipients' iTIP Inboxes.
The server may support fanout to other domains, and the client may attempt to get the server to do this by specifying remote addresses for the fanout recipients, but the server is not bound to support or complete remote fanout operations even if it advertises support for 'calendar-schedule' features. Note that fanout mechanisms are not defined in CalDAV -- there is no server-to-server or server-to-client protocol defined for delivering an iTIP message. Implementations may do this in a proprietary way, with iMIP, or with iTIP bindings as yet unspecified.
After the fanout is completed, CalDAV clients will see the iTIP messages the next time they synchronize or query the iTIP Inbox collection. To reply to an iTIP invitation, the client uses the SCHEDULE method to send another iTIP message (this time, a reply). If the user has decided to accept the invitation, the client also uses PUT (or some other method) to create a VEVENT resource (text/calendar) in the appropriate calendar, and with the appropriate details. Typically, the step of putting the event in the calendar is left up to the client, so that the client can make appropriate choices about where to put the event, and with what alarms, etc. However, the server MAY be configured (how is not defined here) to auto-accept or auto-reject invitations, and if the server auto-accepts invitations then the server is responsible for creating iCalendar components in the user's calendar.
CalDAV defines the following new resource types for use in calendar repositories.
A WebDAV collection which corresponds to a single calendar or VCALENDAR is a Calendar. It has a new resource type:
<resourcetype xmlns="DAV:"> <collection/> <C:calendar xmlns:C="urn:ietf:params:xml:ns:caldav"/> </resourcetype>
The calendar collection contains resources that represent the iCalendar objects within the calendar. It also has certain properties which are required to be present on calendars (see XML section). A Calendar collection may be created through provisioning (e.g. automatically created when a user's account is created), or it may be created through MKCALENDAR. This can be useful for a user to create a second calendar (e.g. soccer schedule) or for users to share a calendar (e.g. team events or conference room). Note however that this proposal doesn't define what extra calendars are for, users must rely on non-standard cues to find out what a calendar is for.
Calendars MUST NOT contain other calendars. Multiple calendars MAY be children of the same WebDAV collection.
A Calendar collection MAY contain additional collections and non-collection resources of types not defined here. How such items are used is not defined by this specification.
Each top-level iCalendar component within the VCALENDAR component is represented as a seperate WebDAV resource, with the exception that sets of recurring items (i.e. components with the same UID iCalendar property value, but differing RECURRENCE-ID values) are all stored in the same resource. i.e. each WebDAV resource MUST only contain iCalendar components with the same iCalendar UID property value, and all iCalendar components with the same iCalendar UID property value MUST be stored in the same WebDAV resource.
For example, given the following iCalendar object:
BEGIN:VCALENDAR CALSCALE:GREGORIAN PRODID:-//Example, Inc.\, Inc.//Example App//EN VERSION:2.0 BEGIN:VEVENT UID:firstname.lastname@example.org SUMMARY:One-off Meeting DTSTAMP:20041210T183904Z DTSTART:20041207T120000Z DTEND:20041207T130000Z END:VEVENT BEGIN:VEVENT UID:email@example.com SUMMARY:Weekly Meeting DTSTAMP:20041210T183838Z DTSTART:20041206T120000Z DTEND:20041206T130000Z RRULE:FREQ=WEEKLY END:VEVENT BEGIN:VEVENT UID:firstname.lastname@example.org RECURRENCE-ID:20041213T120000Z SUMMARY:Weekly Meeting DTSTAMP:20041210T183838Z DTSTART:20041213T130000Z RRULE:FREQ=WEEKLY END:VEVENT END:VCALENDAR
The VEVENT with UID value "email@example.com", would be stored in its own unique WebDAV resource. The two VEVENTs with UID value "firstname.lastname@example.org", which represent a set of recurring events where one instance has been overridden, would be stored in a single unique WebDAV resource.
On a server supporting 'calendar-schedule' features, every Calendar MUST have an associated iTIP Inbox collection to contain incoming iTIP messages. The iTIP Inbox MAY be inside the calendar or elsewhere on the server, possibly even on another server.
<resourcetype xmlns="DAV:"> <collection/> <C:itip-inbox xmlns:C="urn:ietf:params:xml:ns:caldav"/> </resourcetype>
Every non-collection resource in the iTIP Inbox collection is considered to be an iTIP message. Every resource MUST have the media type text/calendar, and contain the iCalendar METHOD property.
On a server supporting 'calendar-schedule' features, 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:itip-outbox xmlns:C="urn:ietf:params:xml:ns:caldav"/> </resourcetype>
Every non-collection resource in the scheduling 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. When the client sends the HTTP SCHEDULE method to an iTIP outbox, the server is responsible for putting a copy of of the iTIP message in that iTIP outbox. This then serves as a record of outgoing scheduling messages.
The server MAY auto-delete messages in the outbox after a suitably long period or to keep within a quota. The server SHOULD allow the calendar owner to DELETE resources in the outbox.
Calendars 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, or the CalDAV client might create a new calendar collection. Servers might populate events as calendar objects inside a calendar collection, or (more typically) clients might create events. Either way, both client and server MUST comply with the requirements in this document, and MUST understand objects appearing in calendars or according to the data model defined here.
The new MKCALENDAR method is defined for the client to tell the server to create a new calendar and populate it with the default property values. If a resource already exists at the Request-URI, or if the Request-URI is contained within a calendar collection, the server MUST fail the request with a 409 (Conflict) error. Permission to use the MKCALENDAR method SHOULD be governed by the 'bind' privilege on the parent collection of the Request-URI. Permission to DELETE a calendar collection SHOULD likewise be governed by the 'unbind' privilege on the parent collection.
If there is no resource at the Request-URI, and the server is capable of creating and supporting a calendar at that location, then the server creates the calendar collection. The server MUST also populate the new collection with the appropriate default property values, particularly for the resourcetype property and calendar-owner property. The successful response to MKCALENDAR is typically 201 (Created).
Note that there is no semantic value in any other part of a calendar name (or a resource name, other than possibly the file extension). Thus, a calendar collection may be called "calendar", "cal", "Calendario" and so on. It's the properties of the resource that define what it is, not the name.
Clients typically populate new calendars with components. The URL for each component resource is entirely arbitrary, and does not need to bear a specific relationship (but might) to the component's subject, scheduled time, UID or other metadata. A brand-new component must obviously have a new URL, otherwise the new component would instead be an update to an existing component.
When servers create new 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 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.
Servers SHOULD return an ETag header containing the actual ETag of the newly created resource on a succesful creation.
>> Request <<
PUT /lisa/calendar/newevent.ics HTTP/1.1 If-None-Match: * Host: cal.example.com Content-Type: text/calendar Content-Length: xxx BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example Corp.//CalDAV Client//EN BEGIN:VEVENT UID:20010712T182145Zemail@example.com DTSTART:20010714T170000Z DTEND:20010715T035959Z SUMMARY:Bastille Day Party END:VEVENT END:VCALENDAR
>> Response <<
HTTP/1.1 201 Created Date: Thu, 02 Sep 2004 16:53:32 GMT Location: http://cal.example.com/lisa/calendar/ev1234.ics Content-Length: 0 ETag: 123456789-000-111
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/calendar" MIME type, whenever creating Calendar objects of that MIME type.
A CalDAV server MAY return the Location header in a 201 (Created) response to a PUT request if the server created the resource at a different URI than the Request-URI. CalDAV clients MUST be able to handle the URI returned by the server in the Location header, by adjusting their original resource URI to the new one returned by the server.
The WebDAV ACL specification requires that any principal to whom permissions can be granted is represented via a special resource that has a HTTP URL as well as WebDAV properties. Thus, both users may be represented (for example, as /principals/users/lisa) and groups (for example, as /principals/groups/dev-team). 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 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.
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.
Not all properties need to be promoted, only those properties most useful for clients to do property value searching or listings of calendar events either through PROPFIND or through the recurrence report. All unrecognized properties can be left in the resource body (such as those beginning with x-).
TODO: This section needs further definition and details. Clients can upload iCalendar files with syntactic or semantic errors, so helpful error codes must be chosen for these cases:
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.
CalDAV servers that return the value "calendar-schedule" in the DAV response header MUST support iTIP to send and receive scheduling requests as well as reply to scheduling request. These servers MUST handle outgoing iTIP messages submitted to an iTIP Outbox collection, and MUST deliver incoming iTIP messages to an iTIP Inbox collection.
TODO: We need to clarify if outgoing iTIP messages that have not yet been delivered to all specified calendars should be accessible as calendar resources in the iTIP Outbox collection.
Incoming iTIP messages may remain in the iTIP Inbox collection until a client deletes them. CalDAV servers MUST parse incoming REPLY messages and update the appropriate event with attendee information. Thus, it's not necessary for clients to review REPLY messages, although they may.
When a CalDAV server receives an iTIP message, it MUST store the object in an iTIP Inbox collection for the client to handle. The message 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 messages 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.
Servers SHOULD NOT delete messages before or after a client has retrieved the messages in the inbox; instead the server SHOULD leave Inbox cleanup to the client. A server MAY apply a quota to the iTIP Inbox (limiting the number of messages, the total size, or some other measurable) and MAY bounce incoming messages if the iTIP inbox is full or some other repository or account problem has occurred.
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 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 SCHEDULE, 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.
To achieve these goals, this section specifies a WebDAV binding for the iCalendar Transport-independent Interoperability Protocol (iTIP ). It provides the necessary information to convey iTIP over WebDAV.
The SCHEDULE method submits an iTIP message specified in the request body to the location specified by the Request-URI. The request body of a SCHEDULE method MUST contain an iCalendar object that obey the restrictions specified in iTIP . The resource identified by the Request-URI MUST be a resource collection of type "itip-outbox" (Section 5.3).
The submitted iTIP message will be delivered to the calendar addresses specified in the Recipient header.
The calendar address of the originator of the iTIP message MUST be specified in the Originator header. This calendar address MUST identify a resource collection of type "itip-inbox" (Section 5.2). that is owned by the currently authenticated user.
The calendar address of the recipient(s) of the iTIP message MUST be specified in the Recipient header. There MUST be at least one Recipient per SCHEDULE request.
The body of the SCHEDULE request is a complete iCalendar component (content type text/calendar), and MUST have an iTIP method. The list of attendees and the organizer information in this request body might well be redundant with the values of the Recipient and Originator headers. This is intentional, so that the client can have more control over who receives invitations and who sends them:
The SCHEDULE request is intended to be independent with the PUT request that stores an event on a particular calendar. This independence gives greater flexibility and control to the client. In the case where the event that is sent with SCHEDULE corresponds to an event stored in a calendar, the client SHOULD submit the PUT request first. That means that when the SCHEDULE request is sent and replies are returned, the server is more likely to have an event on the calendar on which to collate responses and show attendance.
The following are examples of response codes one would expect to be used in a 207 (Multi-Status) response for this method. Note, however, that unless explicitly prohibited any 2/3/4/5xx series response code may be used in a 207 (Multi-Status) response.
200 (OK) - The command succeeded.
202 (Accepted) - The request was accepted, but the server has not performed any action with it yet.
400 (Bad Request) - The client has provided an invalid iTIP message.
403 (Forbidden) - The client, for reasons the server chooses not to specify, cannot submit an iTIP message to the specified Request-URI.
404 (Not Found) - The URL in the Request-URI, the Originator, or the Recipient headers could not be found.
423 (Locked) - The specified resource is locked and the client either is not a lock owner or the lock type requires a lock token to be submitted and the client did not submit it.
502 (Bad Gateway) - The Recipient header contained a URL which the server considers to be in another domain, which it cannot forward iTIP messages to.
507 (Insufficient Storage) - The server did not have sufficient space to record the iTIP message in a recipient's iTIP inbox.
Also, many errors would be appropriate as top-level errors rather than return a 207 (Multi-Status) response. For example, if the server did not have sufficient space to record the iTIP message in the originator's outbox, the server could send a 507 (Insufficient Storage) response with no body.
>> Request <<
SCHEDULE /lisa/calendar/outbox/ HTTP/1.1 Host: cal.example.com Originator: http://cal.example.com/lisa/inbox/ Recipient: http://cal.example.com/bernard/inbox/ Recipient: http://cal.example.com/cyrus/inbox/ Content-Type: text/calendar Content-Length: xxxx BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example Corp.//CalDAV Client//EN METHOD:REQUEST BEGIN:VEVENT DTSTAMP:20040901T200200Z CATEGORIES:APPOINTMENT ORGANIZER:http://cal.example.com/lisa/inbox/ DTSTART:20040902T130000Z DTEND:20040902T140000Z SUMMARY:Design meeting UID:firstname.lastname@example.org ATTENDEE;PARTSTAT=ACCEPTED;ROLE=CHAIR;CUTYPE=IND IVIDUAL;CN=Lisa Dusseault:http://cal.example.co m/lisa/inbox/ ATTENDEE;PARTSTAT=NEEDS-ACTION;ROLE=REQ-PARTICIP ANT;CUTYPE=INDIVIDUAL;CN=Bernard Desruisseaux:h ttp://cal.example.com/bernard/inbox/ ATTENDEE;PARTSTAT=NEEDS-ACTION;ROLE=REQ-PARTICIP ANT;CUTYPE=INDIVIDUAL;CN=Cyrus Daboo:http://cal .example.com/cyrus/inbox/ END:VEVENT END:VCALENDAR
>> Response <<
HTTP/1.1 207 Multi-Status Date: Thu, 02 Sep 2004 16:53:32 GMT Content-Type: text/xml Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:"> <D:response> <D:href>http://cal.example.com/bernard/inbox/</D:href> <D:status>HTTP/1.1 200 OK</D:status> </D:response> <D:response> <D:href>http://cal.example.com/cyrus/inbox/</D:href> <D:status>HTTP/1.1 200 OK</D:status> </D:response> </D:multistatus>
In this example, the client requests the server to deliver an appointment invitation (iTIP REQUEST) in Bernard's and Cyrus's iTIP Inbox collections.
Incoming iTIP messages will be stored in resource collection of type "itip-inbox". The originator of the iTIP message will be specified in the Originator response header. The same rules for property promotion apply to incoming iTIP messages, so a client can also use PROPFIND and REPORT to get some of the most important information on iTIP messages in the iTIP inbox.
>> Request <<
GET /bernard/calendar/inbox/mtg456.ics HTTP/1.1 Host: cal.example.com
>> Response <<
HTTP/1.1 200 OK Date: Thu, 02 Sep 2004 17:05:23 GMT Originator: http://cal.example.com/lisa/inbox/ Content-Type: text/calendar Content-Length: xxxx BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example Corp.//CalDAV Server//EN METHOD:REQUEST BEGIN:VEVENT DTSTAMP:20040901T200200Z CATEGORIES:APPOINTMENT ORGANIZER:http://cal.example.com/lisa/inbox/ DTSTART:20040902T130000Z DTEND:20040902T140000Z SUMMARY:CalDAV draft review UID:email@example.com ATTENDEE;PARTSTAT=ACCEPTED;ROLE=CHAIR;CUTYPE=IND IVIDUAL;CN=Lisa Dusseault:http://cal.example.co m/lisa/inbox/ ATTENDEE;PARTSTAT=NEEDS-ACTION;ROLE=REQ-PARTICIP ANT;CUTYPE=INDIVIDUAL;CN=Bernard Desruisseaux:h ttp://cal.example.com/bernard/inbox/ ATTENDEE;PARTSTAT=NEEDS-ACTION;ROLE=REQ-PARTICIP ANT;CUTYPE=INDIVIDUAL;CN=Cyrus Daboo:http://cal .example.com/cyrus/inbox/ END:VEVENT END:VCALENDAR
TODO: Need to explain here how to handle incoming iTIP messages. If the client wants to accept a message, it needs to create an event and mark the inbox resource as "accepted". If the client wants to reject it, it simply changes a property. Need to define that property. Also recommend locking the Inbox resource to avoid race conditions with other clients -- or use ETags to verify.
Originator = "Originator" ":" absoluteURI
The Originator header value is a URL which identifies an iTIP Inbox collection owned by the originator of an iTIP message submitted with the SCHEDULE method. Note that the absoluteURI production is defined in RFC2396 .
The W3C RDF Calendar group has already defined a namespace ("http://www.w3.org/2002/12/cal/ical#") and XML element names for many calendaring properties, and these are completely consistent with iCalendar. This standard reuses those namespaces, names and definitions, as much as is consistent with the WebDAV data model. Additional properties are needed to describe calendars because the W3C RDF Calendar group defines properties for the iCalendar-defined objects only.
When used as a WebDAV property, each property name/namespace can appear only once because the property name and namespace is used to identify the property in requests like PROPFIND and PROPPATCH. Multi-valued elements could either be promoted to properties by using a container (e.g. an 'attendees' property could hold each 'attendee' element), or multi-valued elements can remain in the iCalendar body, and not be promoted as WebDAV properties. That means clients must download the event body to learn the values for those pieces of metadata.
TODO: Need to reference RFC3339 and put date/time values in that format, and note where that format differs from that of the iCalendar RFC values.
If any of these properties appear in an iCalendar body stored in a CalDAV repository they MUST be promoted. All these properties are in the "http://www.w3.org/2002/12/cal/ical#" namespace.
REQUIRED properties for promotion from iCalendar
|Name||WebDAV Property value type|
|dtstart||date-time from RFC2518|
|dtend||date-time from RFC2518|
|duration||DURATION from RFC2445|
|transp||text with values from RFC2445|
|due||date-time from RFC2518|
|completed||date-time from RFC2518|
|status||text with values from RFC2445|
|recurrence-id||date-time from RFC2518|
|trigger||see below TODO|
|has-recurrence||integer (0 or 1) see Section 11.1|
|has-alarm||integer (0 or 1) see Section 11.2|
|has-attachment||integer (0 or 1) see Section 11.3|
The "has-xxxx" properties listed above do not correspond to properties in iCalendar components. Instead they are synthesised by the WebDAV server based on the component's properties as described in the following sections. These WebDAV properties are available to allow clients to provide hints about component state to the user without the need to explicitly inspect the component data.
The "has-recurrence" property indicates whether the corresponding component contains one or more RRULE, RDATE, EXRULE or EXDATE properties. i.e. the component is recurring. The integer value '1' indicates that at least one of the recurrence properties is present, the integer value '0' indicates that no recurrence properties are present.
The "has-alarm" property indicates whether the corresponding component contains one or more embedded VALARM components. The integer value '1' indicates that at least one embedded VALARM component is present, the integer value '0' indicates that no embedded VALARM components are present.
The namespace "urn:ietf:params:xml:ns:caldav" is reserved for this specification, or standards-track specifications written to extend CalDAV. It MUST NOT be used for custom extensions. It is the namespace for every new property defined in this section (and every XML element defined in this document).
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.
This section defines new properties for WebDAV principal resources as defined in RFC3744 . All these properties SHOULD exist on every principal if the server supports CalDAV anywhere in its namespace. Generally, if no appropriate value is known for these properties, the properties SHOULD exist but be blank. Generally these properties are likely to be protected but the server MAY allow them to be written by appropriate users.
<!ELEMENT alternate-calendar-URI (href*) >
<!ELEMENT calendar-URL (href*) >
<!ELEMENT itip-inbox-URL (href*) >
<!ELEMENT itip-outbox-URL (href*) >
<!ELEMENT primary-itip-inbox-URL (href) >
<!ELEMENT primary-itip-outbox-URL (href) >
A CalDAV server MUST support the WebDAV ACLs standard . That standard provides a framework for an extensible list of privileges on WebDAV collections and ordinary resources. A CalDAV server MUST also support the set of calendar-specific privileges defined in this section.
Calendar users often wish to allow other users to see their free-busy times, without viewing the other details of the calendar events (location, subject, attendees). This allows a significant amount of privacy while still allowing those other users to schedule meetings at times when the calendar owner is likely to be free.
The view-free-busy privilege in the "urn:ietf:params:xml:ns:caldav" namespace controls access to view the start times and end times of free and busy blocks of time. This privilege may be granted on an entire calendar. It may also make sense to grant this privilege on individual events (in which case the time allocated to those events would show up as free in the free-busy rollup to an unauthorized viewer), but a server MAY forbid the free-busy privilege from being used on individual events or event collections. A CalDAV server MUST support the free-busy privilege on a Calendar collection.
<!ELEMENT view-free-busy EMPTY>
The view-free-busy privilege is aggregated in the standard WebDAV 'read' privilege. Clients can discover support for various privileges using the 'DAV:supported-privilege-set' property defined in RFC3744 .
The schedule privilege controls the use of SCHEDULE to submit an iTIP message via an iTIP Outbox collection. A calendar owner will generally have schedule permission on their own outbox and never grant that permission to anybody else. If the privilege is granted to somebody other than the calendar owner, that person is called the delegate, somebody who can issue invitations or replies on behalf of the calendar owner. Thus, if a server receives a SCHEDULE request where the authenticated sender of the SCHEDULE request does not have schedule permission, the server MUST reject the request.
<!ELEMENT schedule EMPTY >
For example, the following ACE, on Bernard's iTIP Outbox, would only grant the privilege to Bernard to schedule on behalf of himself:
<D:ace xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav"> <D:principal> <D:href>http://cal.example.com/users/bernard</D:href> </D:principal> <D:grant> <D:privilege><C:schedule/></D:privilege> </D:grant> </D:ace>
The calendar-bind privilege is used on a iTIP Inbox or on a calendar collection, to govern whether a user may cause new calendar resources (MIME type text/calendar) to be created in the collection. It is similar to the WebDAV 'bind' privilege but more restricted, because it only allows the user to create new resources of certain types. It doesn't, for example, allow the privileged user to create new collections.
Recall that the iTIP Inbox is used to receive iTIP messages. The server automatically creates resources inside the iTIP Inbox when it handles invitations for the inbox's owner. Thus, the calendar-bind privilege determines whether an event organizer is allowed to send an invitation to an attendee and have it appear in their iTIP Inbox.
One way an invitation may appear in an iTIP inbox is with the SCHEDULE request. If the server receives a SCHEDULE request where a calendar inbox is named in the Recipient header, it MUST check to see whether the 'calendar-bind' privilege is granted either to the authenticated sender of the request, OR to the owner of the iTIP Outbox that the request comes from (the Request-URI of the SCHEDULE method). Thus, if user Alice grants Bob calendar-bind privilege on Alice's inbox, and Bob grants Margaret (his assistant) schedule privilege on Bob's outbox, then transitively, Margaret can send a SCHEDULE request to Bob's outbox, where Alice's inbox is named in the Recipient header. If the server's calendar-bind privilege check fails for a given inbox, the rest of the SCHEDULE request may still succeed, but a 403 Forbidden error would appear in the Multi-status response to the SCHEDULE request.
The server SHOULD also attempt to apply the calendar-bind privilege in other situations where it is requested to add a resource to the iTIP inbox. For example, if the server handles invitations received through some other iTIP binding, the server SHOULD try to see if the invitation should be automatically rejected based on the access control on the iTIP inbox.
Outside the iTIP inbox, the same privilege has a slightly different effect, but has the same meaning. If the server receives any HTTP request which would create a new resource inside a calendar, the server MUST check to see whether calendar-bind privilege is granted on that calendar collection.
Typically, not many users will allow others to put events directly on their calendar, instead preferring to see invitations and choose whether to accept. In the exceptional cases, users will allow a select few to directly put events on their calendar, and in these cases, the 'calendar-bind' privilege will be granted to those few. On the other hand, many users are happy to receive invitations from anyone, so an iTIP inbox may grant 'calendar-bind' privilege to all users.
<!ELEMENT calendar-bind EMPTY >
In the WebDAV ACL standard, servers MUST support the 'supported-privilege-set' property to show which privileges are abstract, which privileges are supported, how the privileges relate to another, and to provide text descriptions (particularly useful for custom privileges). The relationships between privileges involves showing which privilege is a subset or a superset of another privilege. For example, because reading the ACL property is considered a more specific privilege than the read privilege (a subset of the total set of actions are allowed), it is aggregated under the read privilege. Although the list of supported privileges MAY vary somewhat from server to server (the WebDAV ACL specification leaves room for a fair amount of diversity in server implementations), some relationships MUST hold for a CalDAV server:
This is a partial example of how the 'supported-privilege-set' property could look on a server supporting CalDAV. Note that aggregation is shown in the structure of the 'supported-privilege' elements containing each other.
<D:supported-privilege-set xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav"> <D:supported-privilege> <D:privilege><D:all/></D:privilege> <D:abstract/> <D:description xml:lang="en">Any operation </D:description> <D:supported-privilege> <D:privilege><D:read/></D:privilege> <D:description xml:lang="en">Read any object </D:description> <D:supported-privilege> <D:privilege><D:read-acl/></D:privilege> <D:description xml:lang="en">Read ACL </D:description> </D:supported-privilege> <D:supported-privilege> <D:privilege><D:read-current-user-privilege-set/> </D:privilege> <D:description xml:lang="en">Read current user privilege set</D:description> </D:supported-privilege> <D:supported-privilege> <D:privilege> <C:view-free-busy/> </D:privilege> <D:description xml:lang="en">View free-busy rollup </D:description> </D:supported-privilege> </D:supported-privilege> <D:supported-privilege> <D:privilege><D:write/></D:privilege> <D:description xml:lang="en">Write any object</D:description> <D:supported-privilege> <D:privilege> <C:calendar-bind/> </D:privilege> <D:description xml:lang="en">Directly schedule (request a meeting) of the owner of this iTIP inbox</D:description> </D:supported-privilege> <D:supported-privilege> <D:privilege> <C:schedule/> </D:privilege> <D:description xml:lang="en">Make schedule requests of others, on behalf of the owner of this iTIP outbox</D:description> </D:supported-privilege> ... </D:supported-privilege> </D:supported-privilege-set>
This section defines the reports which a CalDAV server MUST support on Calendars. 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 so a CalDAV server MUST provide a value for the 'supported-report-set' property.
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: xxxx <?xml version="1.0" encoding="UTF-8" ?> <D:error xmlns:D="DAV:"> <range-invalid xnlns="urn:ietf:params:xml:ns:caldav"/> </D:error>
A WebDAV collection which contains one or more calendars is not a new type of resource, but it may support these new REPORT types. If so, then the REPORT is expected to have the semantics of including information from all the calendar data contained in the collection, and its children, recursively. These collections may contain more than only calendar-related resources. It's up to the server, if it supports this REPORT on a normal WebDAV collection, to find event and free-busy data and decide what to do with non-calendaring resources and whether those may also appear in the collection or its children.
If these reports are supported on ordinary collections the server advertises the capability with the 'supported-report-set' property as already described.
The calendar-query REPORT performs a search for all iCalendar objects that match a specified search filter. The response of this report will contain all the WebDAV properties and iCalendar object data specified in the request. In the case of the calendar-query-result, one can explicitly specify the iCalendar components and properties that should be returned in the iCalendar object data that matches the search filter.
Support for the calendar-query REPORT is REQUIRED.
The marshalling of the body of the calendar-query REPORT request, as well as modifications to the multi-status body used in the REPORT response, are described in the following sections.
The request body MUST be a "calendar-query" XML element.
<!ELEMENT calendar-query (DAV:allprop | DAV:propname | DAV:prop)? calendar-query-result? filter>
The "icalcomp" element defines which components to return in the response.
<!ELEMENT icalcomp ((allicalcomp, (allicalprop | icalprop*)) | (icalcomp*, (allicalprop | icalprop*))) expand-recurrence-set?> <!ATTLIST icalcomp name CDATA #REQUIRED>
name value: an iCalendar component name (e.g., "VEVENT")
The "allicalcomp" element appearing within "icalcomp" specifies that all components shall be returned.
<!ELEMENT allicalcomp EMPTY>
The "allicalprop" element specifies that all properties shall be returned.
<!ELEMENT allicalprop EMPTY>
The 'icalprop' element defines which properties to return in the response.
<!ELEMENT icalprop EMPTY> <!ATTLIST icalprop name CDATA #REQUIRED novalue (yes|no) "no">
The value of the "name" attribute MUST be an iCalendar property name (e.g., "ATTENDEE")
The expand-recurrence-set element specifies that recurring components shall be returned as multiple components with no recurrence properties (i.e., EXDATE, EXRULE, RDATE and RRULE).
<!ELEMENT expand-recurrence-set EMPTY>
TODO: Need to specify how infinite recurrence should be handled. In the case of VTIMEZONE, the expanded VTIMEZONE component should only have to cover the time range covered by the components making reference to the VTIMEZONE component.
ISSUE: Should we have another XML element to specify whether all component instances of a recurring component should be returned, or only the specific instances that matched the specified filter? For instance, if you search for all VEVENT components that are scheduled today and you didn't specify the expand-recurrence-set element, then you may receive recurring VEVENT components that will define recurrence instances for other dates than today. On the other hand, if you have specified the expand-recurrence-set element, the server could return only the recurrence instances that are scheduled today and omit the others.
The 'filter' element specifies the search filter.
<!ELEMENT filter icalcomp-filter>
The 'icalcomp-filter' limits the search result to the set of resources containing components that meet the filter rules.
<!ELEMENT icalcomp-filter (is-defined | time-range)? icalcomp-filter* icalprop-filter*> <!ATTLIST icalcomp-filter name CDATA #REQUIRED>
When this element is present, the server should only return a component if it matches the filter, which is to say:
("no is-defined element" OR "is-defined matches") AND ("no time-range element" OR "time-range matches") AND ("no sub-component filter" OR "all sub-component filters match") AND ("no property filter elements" OR "all property filters match")
The 'icalprop-filter' limits the search result to the set of resources containing components with properties that meet the property filter rules.
<!ELEMENT icalprop-filter (is-defined | time-range | text-match)? icalparam-filter*> <!ATTLIST icalprop-filter name CDATA #REQUIRED>
When the 'icalprop-filter' executes, a property matches if:
("no is-defined element" OR "is-defined matches") AND ("no time-range element" OR "time-range matches") AND ("no text match element" OR "text-match matches") AND ("no parameter filter elements" OR "all parameter filters match")
The 'icalparam-filter' element limits the search result to the set of resources containing properties with parameters that meet the parameter filter rules.
<!ELEMENT icalparam-filter (is-defined | text-match) > <!ATTLIST icalparam-filter name CDATA #REQUIRED>
When this filter executes, a parameter matches if:
("is-defined matches" OR "text-match matches")
The 'is-defined' element limits the filter to resources where the named component, property or parameter is defined.
<!ELEMENT is-defined EMPTY>
The text-match element allows for substring matches in parameter and property values.
<!ELEMENT text-match #PCDATA> <!ATTLIST text-match caseless (yes|no)>
TODO: We need to decide if we want to allow wildcards characters such as '?' and '%'.
The "caseless" attribute allows clients to specify caseless matching behaviour instead of character-by-character matching for text-match. The possible values for "caseless" are "yes" or "no". The default value is server-specified. Caseless matching SHOULD be implemented as defined in section 5.18 of the Unicode Standard ([UNICODE4]).
Support for the "caseless" attribute is optional. A server should respond with a status of 422 if it is used but cannot be supported.
The time-range element allows for a single time range to be defined, in order to limit all the results of the search to the set of resources that contain a component which falls into that time range.
<!ELEMENT time-range EMPTY> <!ATTLIST time-range start CDATA end CDATA>
The value of the "start" and "end" attributes MUST follow the syntax of the DATE or DATE-TIME iCalendar value type.
A VEVENT component falls in a given time-range if:
(DTSTART <= start AND DTEND > start) OR (DTSTART <= start AND DTSTART+DURATION > start) OR (DTSTART >= start AND DTSTART < end) OR (DTEND > start AND DTEND <= end)
A VTODO component falls in a given time-range if:
(DTSTART <= start AND DUE >= start) OR (DTSTART <= start AND DTSTART+DURATION > start) OR (DTSTART >= start AND DTSTART < end) OR (DUE >= start AND DUE < end)
A VJOURNAL component falls in a given time-range if:
DTSTART >= start AND DTSTART < end
A VALARM component falls in a given time-range if:
trigger-time >= start AND trigger-time < end
Any property of value type DATE-TIME or DATE (e.g., DTSTAMP) will match a given time-range if:
value >= start AND value < end
In this example, the client requests the server to return specific components and properties of the VEVENT components that overlap the time range from September 2nd, 2004 at 00:00:00 am UTC to September 2nd, 2004 at 11:59:59 pm UTC. In addition the WebDAV "getetag" property is also requested and returned as part of the response.
>> Request <<
REPORT /bernard/calendar/ HTTP/1.1 Host: cal.example.com Depth: 1 Content-Type: text/xml Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <C:calendar-query xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav"> <D:prop> <D:getetag/> </D:prop> <C:calendar-query-result> <C:icalcomp name="VCALENDAR"> <C:allicalprop/> <C:icalcomp name="VEVENT"> <C:icalprop name="X-ABC-GUID"/> <C:icalprop name="UID"/> <C:icalprop name="DTSTART"/> <C:icalprop name="DTEND"/> <C:icalprop name="DURATION"/> <C:icalprop name="EXDATE"/> <C:icalprop name="EXRULE"/> <C:icalprop name="RDATE"/> <C:icalprop name="RRULE"/> <C:icalprop name="LOCATION"/> <C:icalprop name="SUMMARY"/> </C:icalcomp> <C:icalcomp name="VTIMEZONE"> <C:allicalprop/> <C:allicalcomp/> </C:icalcomp> </C:icalcomp> </C:calendar-query-result> <C:filter> <C:icalcomp-filter name="VCALENDAR"> <C:icalcomp-filter name="VEVENT"> <C:time-range start="20040902T000000Z" end="20040902T235959Z"> </C:icalcomp-filter> </C:icalcomp-filter> </C:filter> </C:calendar-query>
>> Response <<
HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav"> <D:response> <D:href>http://cal.example.com/bernard/calendar/ev102.ics</D:href> <D:propstat> <D:prop> <D:getetag>23ba4d-ff11fb</D:getetag> </D:prop> <D:status>HTTP/1.1 200 OK</D:status> </D:propstat> <C:calendar-query-result>BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example Corp.//CalDAV Client//EN BEGIN:VEVENT DTSTART:20040902T100000Z DTEND:20040902T120000Z SUMMARY:Design meeting UID:firstname.lastname@example.org X-ABC-GUID:E1CX4zp-0005Ldemail@example.com END:VEVENT END:VCALENDAR </C:calendar-query-result> </D:response> <D:response> <D:href>http://cal.example.com/bernard/calendar/mtg103.ics</D:href> <D:propstat> <D:prop> <D:getetag>ff11fb-23ba4d</D:getetag> </D:prop> <D:status>HTTP/1.1 200 OK</D:status> </D:propstat> <C:calendar-query-result>BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example Corp.//CalDAV Client//EN BEGIN:VEVENT DTSTART:20040902T130000Z DTEND:20040902T150000Z SUMMARY:Design meeting - Part II UID:firstname.lastname@example.org X-ABC-GUID:E1CX5Dr-0007ym-Hz@example.com END:VEVENT END:VCALENDAR </C:calendar-query-result> </D:response> </D:multistatus>
In this example, the client requests the server to return the VTODO components that have an alarm trigger scheduled in the specified time range. No WebDAV properties are requested.
>> Request <<
REPORT /bernard/calendar/ HTTP/1.1 Host: cal.example.com Depth: 1 Content-Type: text/xml Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <C:calendar-query xmlns:C="urn:ietf:params:xml:ns:caldav"> <C:calendar-query-result/> <C:filter> <C:icalcomp-filter name="VCALENDAR"> <C:icalcomp-filter name="VTODO"> <C:icalcomp-filter name="VALARM"> <C:time-range start="20041121T000000Z" end="20041121T235959Z"> </C:icalcomp-filter> </C:icalcomp-filter> </C:icalcomp-filter> </C:filter> </C:calendar-query>
In this example, the client requests the server to return the VEVENT component that has the UID property set to "20041121-FEEBDAED@foo.org". No WebDAV properties are requested.
>> Request <<
REPORT /bernard/calendar/ HTTP/1.1 Host: cal.example.com Depth: 1 Content-Type: text/xml Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <C:calendar-query xmlns:C="urn:ietf:params:xml:ns:caldav"> <C:calendar-query-result/> <C:filter> <C:icalcomp-filter name="VCALENDAR"> <C:icalcomp-filter name="VEVENT"> <C:icalprop-filter name="UID"> <C:text-match caseless="no">20041121-FEEBDAED@foo.org</C:text-match> </C:icalprop-filter> </C:icalcomp-filter> </C:icalcomp-filter> </C:filter> </C:calendar-query>
In this example, the client requests the server to return the VEVENT components that have the ATTENDEE property with the value "mailto:email@example.com" and for which the PARTSTAT parameter is set to "NEEDS-ACTION". No WebDAV properties are requested.
>> Request <<
REPORT /bernard/calendar/ HTTP/1.1 Host: cal.example.com Depth: 1 Content-Type: text/xml Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <C:calendar-query xmlns:C="urn:ietf:params:xml:ns:caldav"> <C:calendar-query-result/> <C:filter> <C:icalcomp-filter name="VCALENDAR"> <C:icalcomp-filter name="VEVENT"> <C:icalprop-filter name="ATTENDEE"/> <C:text-match caseless="yes">mailto:firstname.lastname@example.org</C:text-match> <C:icalparam-filter name="PARTSTAT"/> <C:text-match caseless="no">NEEDS-ACTION</C:text-match> </C:icalparam-filter> </C:icalprop-filter> </C:icalcomp-filter> </C:icalcomp-filter> </C:filter> </C:calendar-query>
In this example, the client requests the server to return all VEVENT components. No WebDAV properties are requested.
>> Request <<
REPORT /bernard/calendar/ HTTP/1.1 Host: cal.example.com Depth: 1 Content-Type: text/xml Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <C:calendar-query xmlns:C="urn:ietf:params:xml:ns:caldav"> <C:calendar-query-result/> <C:filter> <C:icalcomp-filter name="VCALENDAR"> <C:icalcomp-filter name="VEVENT"> <C:is-defined/> </C:icalcomp-filter> </C:icalcomp-filter> </C:filter> </C:calendar-query>
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 particular, we need to understand how UID/SEQ metadata works with synchronization.
Note that recurrence 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 recurrences. Instead, recurrences 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 recurrences) is crucial to simplifying synchronization.
In addition to the namespaces defined by RFC2518  for XML elements, this document uses a URN to describe a new XML namespace conforming to a registry mechanism described in RFC3688 . All other IANA considerations mentioned in RFC2518  also apply to this document.
|||Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifiers (URI): Generic Syntax”, RFC 2396, August 1998.|
|||Dawson, F., Stenerson, D., “Internet Calendaring and Scheduling Core Object Specification (iCalendar)”, RFC 2445, November 1998.|
|||Silverberg, S., Mansour, S., Dawson, F., and R. Hopson, “iCalendar Transport-Independent Interoperability Protocol (iTIP) Scheduling Events, BusyTime, To-dos and Journal Entries”, RFC 2446, November 1998.|
|||Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1”, RFC 2616, June 1999.|
|||Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. Jensen, “HTTP Extensions for Distributed Authoring -- WEBDAV”, RFC 2518, February 1999.|
|||Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps”, RFC 3339, July 2002.|
|||Mealling, M., “The IETF XML Registry”, BCP 81, RFC 3688, January 2004.|
|||Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, “Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol”, RFC 3744, May 2004.|
|||W3C, “iCalendar Schema in RDF/XML”, site http://www.w3.org/2002/12/cal/ical, December 2002.|
|||Hoffman, P., Masinter, L., and J. Zawinski, “The mailto URL scheme”, RFC 2368, July 1998.|
|||Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. Whitehead, “Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning)”, RFC 3253, March 2002.|
|||Reschke, J., Reddy, S., Davis, J., and A. Babich, “WebDAV SEARCH (DASL)”, Internet-Draft draft-reschke-webdav-search-06 (work in progress), August 2004.|
5001 Baum Blvd
Pittsburgh, PA 15213
600 blvd. de Maisonneuve West
Montreal, QC H3A 3J2
Open Source Application Foundation
2064 Edgewood Dr.
Palo Alto, CA 94303
Basically still adding major sections of content:
Copyright © The Internet Society (2004).
This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.
This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
The IETF takes no position regarding the validity or scope of any Intellectual Property Rights 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; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat 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 implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at email@example.com.