Scheduling Extensions to CalDAV

This document specifies a set of methods, headers and resource types that define the scheduling extension to the CalDAV protocol. CalDAV itself extends WebDAV, which extends HTTP. The new protocol elements defined here allow interoperable scheduling operations on a CalDAV repository.¶

1. Introduction

This document specifies a set of methods, headers, properties and privileges that define the CalDAV scheduling extensions to the WebDAV [7] protocol. This document also provides the transport specific information necessary to convey iCalendar Transport-independent Interoperability Protocol iTIP [5] over WebDAV which enables transactions such as publish, schedule, reschedule, respond to scheduling requests, negotiation of changes or cancel iCalendar-based calendar components.¶

1.1. XML Namespaces

Definitions of XML elements in this document use XML element type declarations (as found in XML Document Type Declarations), described in Section 3.2 of [13].¶

The namespace "urn:ietf:params:xml:ns:caldav" is reserved for the XML elements defined in this specification, or in other Standards Track IETF RFCs written to extend CalDAV. It MUST NOT be used for proprietary extensions.¶

Note that the XML 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 XML element type. Some of the declarations refer to XML elements defined by WebDAV which use the "DAV:" namespace. Wherever such elements appear, they are explicitly given the "DAV:" prefix to help avoid confusion.¶

Also note that some CalDAV XML element names are identiqual to WebDAV XML element names, though their namespace differs. Care MUST be taken not to confuse the two sets of names.¶

1.2. Notational Conventions

The augmented BNF used by this document to describe protocol elements is described in Section 2.1 of [8]. Because this augmented BNF uses the basic production rules provided in Section 2.2 of [8], those rules apply to this document as well.¶

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [1].¶

When XML element types in the namespaces "DAV:" and "urn:ietf:params:xml:ns:caldav" are referenced in this document outside of the context of an XML fragment, the string "DAV:" and "CALDAV:" will be prefixed to the element types respectively.¶

1.3. Method Preconditions and Postconditions

A "precondition" of a method describes the state of the server that must be true for that method to be performed. A "postcondition" of a method describes the state of the server that must be true after that method has been completed. If a method precondition or postcondition for a request is not satisfied, the response status of the request MUST be either 403 (Forbidden) if the request should not be repeated because it will always fail, or 409 (Conflict) if it is expected that the user might be able to resolve the conflict and resubmit the request.¶

In order to allow better client handling of 403 and 409 responses, a distinct XML element type is associated with each method precondition and postcondition of a request. When a particular precondition is not satisfied or a particular postcondition cannot be achieved, the appropriate XML element MUST be returned as the child of a top-level DAV:error element in the response body, unless otherwise negotiated by the request. In a 207 Multi-Status response, the DAV:error element would appear in the appropriate DAV:responsedescription element.¶

4. Scheduling Model

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 participation status sent back to the organizer in a related process. This section is a brief overview of how scheduling workflows relate to the data model of CalDAV.¶

To do scheduling, we need to model iTIP messages received by the server as well as iTIP messages sent by the server on behalf of a scheduling client. Each iTIP message is a CalDAV resource containing an iCalendar object that has an iTIP METHOD property defined. We put inbound and outbound iTIP messages in separate collections, so that the client can easily locate relevant messages and assign scheduling privileges.¶

The iTIP Inbox collection contains received iTIP messages. Received replies (typically containing attendance information) may be automatically parsed and the contained information can be applied to the calendar. The Inbox contains inbound iTIP messages after they are handled/seen by the user, because this serves as a track record and to help synchronize between multiple clients.¶

The iTIP Outbox collection contains sent iTIP messages, which need to be tracked both to help synchronize between multiple clients and to support delegation use cases. 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 might not.)¶

Thus, for every scheduling request, there should be one copy in the organizer's iTIP Outbox, as well as one copy in each attendee's iTIP Inbox. This document defines the SCHEDULE method to request that the server place a copy of an iTIP message in a given iTIP Outbox, and to deliver the iTIP message to the recipients' iTIP Inboxes.¶

The server may support delivery of iTIP messages to other CalDAV servers, and the client may attempt to get the server to do this by specifying remote addresses for the 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 REQUEST, the client uses the SCHEDULE method to send another iTIP message (this time, a REPLY). If the user has decided to accept the REQUEST, the client also uses PUT (or some other method) to create a calendar resource (text/calendar) in the appropriate calendar collection, and with the appropriate details. The step of putting the calendar resource in the calendar is left up to the client, so that the client can make appropriate choices about where to put the calendar resource, 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 calendar resources in the user's calendar collection.¶

Multiple Calendars MAY share an iTIP Inbox collection, because an iTIP Inbox maps more closely to a principal (e.g., a person) than a calendar does. A person may have multiple calendars representing different spheres of activity, but a scheduling request is unlikely to address the correct sphere of activity. Instead, scheduling requests are modelled as addressing a user's iITIP Inbox, and the client accepting the scheduling request decides what Calendar the request belongs to. Similarly, multiple calendars MAY share the same iTIP Outbox collection, because we model scheduling requests as coming from an iTIP Outbox, not the calendar.¶

6. Scheduling and Fanout

Scheduling and fanout is a valuable function provided by 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.¶

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 [5]). It provides the necessary information to convey iTIP over WebDAV.¶

6.1. SCHEDULE Method

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

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 CALDAV:itip-inbox (Section 5.1). 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.¶

6.1.1. Status Codes for use with 207 (Multi-Status)

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

6.1.2. Example - Simple appointment invitation

>> 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:34222-232@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

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

6.2. Retrieving incoming iTIP Messages

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 reports work on iTIP collections, so the client can use REPORT to get partial information on iTIP messages in the iTIP inbox.¶

6.2.1. Example - Retrieve incoming iTIP Message

>> 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:34222-232@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

6.3. Acting on incoming iTIP messages

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

8. Scheduling Access Control

8.1. Scheduling Privileges

A CalDAV server MUST support the WebDAV ACLs standard [11]. 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.¶

8.1.1. CALDAV:schedule Privilege

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>

8.1.2. CALDAV:calendar-bind Privilege

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

8.1.3. Privilege aggregation and the DAV:supported-privilege-set property

The schedule and calendar-bind privileges MUST be non-abstract, and MUST be aggregated under the 'bind' privilege. These MUST appear in the 'supported-privilege-set' property.¶

8.2. Additional Principal Properties

This section defines new properties for WebDAV principal resources as defined in RFC3744 [11]. All these properties SHOULD exist on every principal if the server supports CalDAV scheduling 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.¶

8.2.1. CALDAV:itip-inbox-URL Property

Name:: itip-inbox-URL
Namespace:: urn:ietf:params:xml:ns:caldav
Purpose:: Identify the URL of the iTIP Inbox collection owned by the associated principal resource.

    <!ELEMENT itip-inbox-URL href>

8.2.2. CALDAV:itip-outbox-URL Property

Name:: itip-outbox-URL
Namespace:: urn:ietf:params:xml:ns:caldav
Purpose:: Identify the URL of the iTIP Outbox collection owned by the associated principal resource.

    <!ELEMENT itip-outbox-URL href>

8.2.3. CALDAV:alternate-calendar-URI Property

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

    <!ELEMENT alternate-calendar-URI (href*) >

13. Normative References