Calendaring and Scheduling Extensions to WebDAV (CalDAV)

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.¶

>> 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

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.¶

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 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 recurrences of an appointment. With these considerations, this proposal does not treat 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.¶

VTIMEZONE components are primarily used within other iCalendar components, when a recurrance rule needs to specify what timezone the recurrance occurs in. Since CalDAV contains iCalendar components that may contain recurrances, of course those recurrances may contain VTIMEZONEs. This makes it a little harder for servers to expand recurrances, but otherwise CalDAV servers have little to do with VTIMEZONE components. There is no place to store VTIMEZONE components on their own, either in a user's calendar or in a central location.¶

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.¶

The calendar collection contains sub-collections with specific kinds of calendar objects. 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 has a specified substructure. It MAY contain one event collection, 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.¶

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. Clients MUST be prepared to identify and navigate multiple event collections within a Calendar. An event collection has its own resource type so these collections are easily identifiable. The server creates an event collection automatically within every calendar because there is no standard way for a user to create an event collection without creating a calendar. Likewise, the server MUST forbid DELETE of an event collection.¶

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.¶

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. The server creates a todo collection within every calendar because there is no standard way for a user to create a todo collection without creating a calendar. Likewise, the server MUST forbid DELETE of a todo collection.¶

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.¶

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. The server creates a journal collection within every calendar because there is no standard way for a user to create a journal collection without creating a calendar. Likewise, the server MUST forbid DELETE of a journal collection.¶

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.¶

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.¶

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.¶

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.¶

The new MKCALENDAR method is defined for the client to tell the server to create a new calendar and populate it with the available internal collections and default property values. If a resource already exists at the Request-URI, 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 not only the calendar collection requested, but also all the possible sub-collections that relate to calendaring. For example, if the server supports both events and todos, then when the server creates the calendar collection it MUST also create the events and todos collections inside the calendar. The server MUST also populate the new collections 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: events in the events collection, and todos in the todos collection. 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.¶

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.¶

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 [4]. The resource identified by the Request-URI MUST be a resource collection of type "itip-outbox" (Section 5.6).¶

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.5). 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 client may send invitations to calendar users not on the attendee list (for example, to an assistant, caterer, observer, etc).
• The client may choose not to send invitations to calendar users who are on the attendee list (for example, attendees who have been scheduled through an out-of-band mechanism).
• The originator may be different than the organizer, for example an assistant who has calendar-bind privileges on the organizer's calendar.

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.¶

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.¶

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.¶

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 [2].¶

The Recipient header value is a URL which identifies one or more iTIP Inbox collections to which the SCHEDULE method should delivered a submitted iTIP message. Note that the absoluteURI production is defined in RFC2396 [2] ¶

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 "has-attachment" property indicates whether the corresponding component contains one or more ATTACH properties. The integer value '1' indicates that at least one ATTACH property is present, the integer value '0' indicates that no ATTACH properties are present.¶

Name:

calendar-owner

Location:

MUST appear on a calendar if there is a principal resources (user or group) with which it is associated.

Purpose:

This property is used for browsing clients to find out the user, group or resource for which the calendar events are scheduled. Sometimes the calendar is a user's calendar, in which case the value SHOULD be the user's principal URL from WebDAV ACL. (In this case the DAV:owner property probably has the same principal URL value.)

If the calendar is a group calendar the value SHOULD be the group's principal URL. (In this case the DAV:owner property probably specifies one user who manages this group calendar.)

If the calendar is a resource calendar (e.g. for a room, or a projector) there won't be a principal URL, so some other URL SHOULD be used. A LDAP URL could be useful in this case.

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.

Name:

cal-scale

Location:

MAY appear on a calendar.

Purpose:

This property's value is a string in the same syntax/values as the CALSCALE property in iCalendar. Only Gregorian calendars are defined so far, so if this property is missing or empty, the calendar is assumed to be a Gregorian calendar.

Declaration:

<!ELEMENT cal-scale (#PCDATA) >

Extensibility:

None

Name:

alternate-calendar-URI

Namespace:

urn:ietf:params:xml:ns:caldav

Purpose:

Identify the URI of an alternate calendar or scheduling resource for the associated principal resource.

Description:

The alternate-calendar-URI property is used to provide a resource address or identifier, such as a mailto URL [1] calendar address, that can be used as an alternative to the primary-itip-inbox-URL of the associated resource in the Originator or Recipient headers. This property SHOULD contain the mailto URL if it is known to accept iMIP requests, because clients generally need a way to find out if some calendar user for whom the iMIP address is known is the same calendar user for whom the iTIP Inbox address is known, and this property is the only reliable way to link those addresses together.

Value:

Zero or more URIs

Name:

calendar-URL

Namespace:

urn:ietf:params:xml:ns:caldav

Purpose:

Identify the URL of any calendar collections owned by the associated principal resource.

Value:

Zero or more URLs

Name:

itip-inbox-URL

Namespace:

urn:ietf:params:xml:ns:caldav

Purpose:

Identify the URL of any iTIP Inbox collections owned by the associated principal resource.

Value:

Zero or more URLs

Name:

itip-outbox-URL

Namespace:

urn:ietf:params:xml:ns:caldav

Purpose:

Identify the URLs of any iTIP Outbox collections owned by the associated principal resource.

Value:

Zero or more URLs

Name:

primary-itip-inbox-URL

Namespace:

urn:ietf:params:xml:ns:caldav

Purpose:

Identify the URL of the principal iTIP Inbox collection owned by the associated principal resource. A principal resource may have many iTIP Inbox collection, but it must have one "principal iTIP Inbox".

Value:

URI

Name:

primary-itip-outbox-URL

Namespace:

urn:ietf:params:xml:ns:caldav

Purpose:

Identify the URL of the principal iTIP Outbox collection owned by the associated principal resource. A principal resource may have many iTIP Outbox collection, but it must have one "principal iTIP Outbox".

Value:

URI

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 [11].¶

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 >¶

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: ¶

• The server MUST support the view-free-busy privilege. The view-free-busy privilege MUST be non-abstract, and MUST be aggregated under the read privilege.
• If the server supports scheduling, the server MUST support the schedule and calendar-bind privileges. Both these privileges MUST be non-abstract, and MUST be aggregated under the 'bind' privilege.

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-time-range' report returns all objects of a specific type within a time range, with or without recurrence 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 recurrence 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.¶

The calendar-property-search REPORT performs a search for all calendar objects whose properties contain character data that matches the search criteria specified in the request. The authors anticipate that this report will be required if DASL is not standardized before CalDAV.¶

Support for the calendar-property-search REPORT is REQUIRED.¶

Marshalling: TODO¶

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, recurrence-id.¶

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.¶

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.¶

URI: urn:ietf:params:xml:ns:caldav¶

Registrant Contact: See the "Author's Address" section of this document.¶

XML: None. Namespace URIs do not represent an XML specification.¶

1. Removed Calendar Containers (simplification that doesn't seem to remove much functionality)
2. Added MKCALENDAR to create calendars and all sub-collections
3. Added cal-scale property to calendars

Basically still adding major sections of content: ¶

1. Defined new field values to the OPTIONS "DAV:" response header
2. Added new resource properties
3. Added new principal properties
4. Added new SCHEDULE method and related headers
5. Added new privileges for scheduling

1. Added section on privileges for calendaring, extending WebDAV ACL privilege set
2. Defined what to do with unrecognized properties in the bodies of iCalendar events, with respect to property promotion/demotion