Scheduling Extensions to CalDAV

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

The namespace "urn:ietf:params:xml:ns:caldav" is reserved for the XML elements defined in this specification, 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 types. 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. Additionally, some of the elements used here are defined in CalDAV [I-D.dusseault-caldav].¶

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

The augmented BNF used by this document to describe protocol elements is described in Section 2.1 of [RFC2616]. Because this augmented BNF uses the basic production rules provided in Section 2.2 of [RFC2616], 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 [RFC2119].¶

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

Scheduling message:

A message that describes a transaction such as publish, schedule, reschedule, respond to scheduling requests, negotiation of changes or cancel calendar components.

Free busy message:

A message that describes a transaction such as publish unsolicited busy time information, request busy time information, or respond to a busy time request.

>> 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, ACL
DAV: 1, 2, access-control, calendar-access, calendar-schedule
Content-Length: 0
        

In this example, the OPTIONS response indicates that the server supports both the calendar-access and calendar-schedule features and that /lisa/calendar/outbox/ can be specified as a Request-URI to the POST method.¶

It is useful for each participant in a scheduling transaction to maintain their own "history" of invitations sent and received during the process and after to keep track of what was done, and to properly handle updates to invitations as they may change over time. This history is usually kept separate from the actual "booked" event, to-do, or daily journal entry, which would normally be placed in a user's calendar collection.¶

In addition, it is useful to keep outgoing invitations separate from incoming ones for organizational purposes.¶

Also, a calendar user may have multiple calendars representing different spheres of activity, but scheduling requests are targeted at calendar user addresses, and there is no formal way to have those indicate which sphere of activity they might apply to. By storing all incoming scheduling requests in a separate collection, clients can process the requests in that collection and choose what calendar the request belongs to and make its own arrangements to place the relevant calendar object in that calendar to "book" it.¶

This specification introduces two new collection resource types that are used for keeping incoming and outgoing scheduling messages separate from other calendar object resources. These can also be used to control who is able to send scheduling messages on behalf of a user, and who is allowed to send scheduling messages to other users by the use of new WebDAV ACL [RFC3744] privileges. Note that these collections only contains scheduling messages that pertains to the scheduling of events, to-dos and daily journal entries. Scheduling messages that describes requests for available busy time information, or replies to such request, are not contained in these collections.¶

The scheduling "Inbox" collection contains received scheduling messages. Scheduling messages are contained in calendar object resources. Each calendar object resource has a WebDAV property that indicates whether the scheduling message has already been processed or not so that multiple clients do not repeat the processing actions already done.¶

The scheduling "Outbox" collection contains scheduling message that have been sent, 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.¶

The iCalendar Transport-independent Interoperability Protocol (iTIP) [RFC2446] outlines a model for scheduling and free-busy message exchanges to perform scheduling transactions. This specification makes use of scheduling free-busy messages to handle scheduling transactions on the server by having such messages passed between different users on the server depending on their role in the scheduling process.¶

To that end each scheduling message is modeled as a calendar object resource which contains the iCalendar object that conforms to the iTIP requirements for the type of transaction being requested.¶

This specification defines the POST method, acting on an Organizer's scheduling Outbox, to trigger schedule processing by the server. This can take one of two forms: for free-busy messages the POST request returns immediately with free busy results; for scheduling messages, a copy of the scheduling message specified in the request body is deposited into each recipient's scheduling Inbox.¶

The server may support delivery of scheduling messages to other CalDAV servers if the client specifies a remote calendar user address for any recipient, but the server is not bound to support or complete remote delivery operations even if it advertises support for the "calendar-schedule" feature. Note that remote delivery mechanisms are not defined in this specification. This specification does not define a server-to-server or server-to-client protocol to deliver remote scheduling messages. Implementations may do this in a proprietary way, with iMIP [RFC2447], or with iTIP bindings as yet unspecified.¶

After the delivery is completed, CalDAV clients will see the scheduling message the next time they synchronize or query a scheduling Inbox collection. To reply to a scheduling REQUEST, the client uses the POST method to send another scheduling message (this time, a REPLY) back to the "Organizer". If the user has decided to accept the REQUEST, the client can create a suitable calendar object resource in the appropriate calendar collection for the recipient. The step of putting the calendar object resource in the calendar is left up to the client, so that the client can make appropriate choices about where to put the calendar object resource, and with what alarms, etc. However, the server MAY be configured to automatically accept or reject invitations, and if the server auto-accepts invitations then the server is responsible for creating calendar object resources in a calendar collection specified by the user.¶

A scheduling Inbox collection contains incoming scheduling messages. These may be requests sent by an Organizer, or replies sent by an Attendee in response to a request.¶

A scheduling Inbox collection MUST report the DAV:collection and CALDAV:schedule-inbox XML elements in the value of the DAV:resourcetype property. The element type declaration for CALDAV:schedule-inbox is: ¶

   <!ELEMENT schedule-inbox EMPTY>
          

Example: ¶

   <resourcetype xmlns="DAV:">
     <collection/>
     <C:schedule-inbox xmlns:C="urn:ietf:params:xml:ns:caldav"/>
   </resourcetype>
          

Every non-collection resource in the scheduling Inbox collection MUST be a valid calendar object resource that defines a scheduling message (e.g., an iCalendar object that follows the iTIP semantic). Note, that unlike calendar collections defined by the calendar-access feature, there are no restrictions on the nature of the resources stored (e.g., there is no need to verify that the UIDs in each resource are unique) beyond the restrictions of iTIP itself. The removal of the UID restriction, in particular, is needed because multiple scheduling messages may be sent for one particular calendar component, and each of those will have the same UID property in the calendar object resource.¶

A new access control privilege can be set on the scheduling Inbox collection to control who is allowed to send scheduling messages to the calendar user associated with the scheduling Inbox. See Section 8.1 for more details.¶

A scheduling Outbox collection contains outgoing scheduling messages. These may be requests initiated by or on behalf of the calendar user associated with the scheduling Outbox, or responses to requests received by the calendar user associated with the scheduling Outbox.¶

A scheduling Outbox collection MUST report the DAV:collection and CALDAV:schedule-outbox XML elements in the value of the DAV:resourcetype property. The element type declaration for CALDAV:schedule-outbox is: ¶

   <!ELEMENT schedule-outbox EMPTY>
          

Example: ¶

   <resourcetype xmlns="DAV:">
     <collection/>
     <C:schedule-outbox xmlns:C="urn:ietf:params:xml:ns:caldav"/>
   </resourcetype>
          

Every non-collection resource in the scheduling Outbox collection MUST be a valid calendar object resource that defines a scheduling message (e.g., an iCalendar object that follows the iTIP semantic). When a client targets the POST method at a scheduling Outbox, the server MAY create a copy of the scheduling message in that scheduling Outbox, unless the POST method corresponds to a free-busy message, in which case the server MUST NOT store a copy of the free-busy message. Copies that are created serve as a record of outgoing scheduling messages.¶

The server MAY auto-delete calendar object resources in the scheduling Outbox (e.g., after a period of time or to keep within a quota).¶

A new access control privilege can be used on the scheduling Outbox collection to control who is allowed to send scheduling messages on behalf of the calendar user associated with the scheduling Outbox. See Section 8.1 for more details.¶

This section describes new WebDAV properties on scheduling Inbox collection resources.¶

This section describes new WebDAV properties for calendar object resources stored in scheduling Inbox or Outbox collections.¶

The POST method submits a scheduling or free-busy message to one or more recipients by targeting the request at the URI of a scheduling Outbox collection. The request body of a POST method MUST contain a scheduling message or free-busy message (e.g., an iCalendar object that follows the iTIP semantic). The resource identified by the Request-URI MUST be a resource collection of type CALDAV:schedule-outbox (Section 5.2).¶

A submitted scheduling message will be delivered to the calendar user addresses specified in the Recipient request header. A submitted free-busy message will be immediately executed and a free-busy response returned.¶

Preconditions: ¶

• (CALDAV:supported-collection): The Request-URI MUST identify the location of a scheduling Outbox collection;
• (CALDAV:supported-calendar-data): The resource submitted in the POST request MUST be a supported media type (i.e., text/calendar) for scheduling or free-busy messages;
• (CALDAV:valid-calendar-data): The resource submitted in the POST request MUST be valid data for the media type being specified (i.e., valid iCalendar object);
• (CALDAV:valid-scheduling-message): The resource submitted in the POST request MUST obey all restrictions specified for the POST request (e.g., scheduling message follows the restriction of iTIP);
• (CALDAV:originator-specified): The POST request MUST include a valid Originator request header specifying a calendar user address of the currently authenticated user;
• (CALDAV:originator-allowed): The calendar user identified by the Originator request header in the POST request MUST be granted the CALDAV:schedule privilege or a suitable sub-privilege on the scheduling Outbox collection being targeted by the request;
• (CALDAV:organizer-allowed): The calendar user identified by the ORGANIZER property in the POST request's scheduling message MUST be the calendar user (or one of the calendar users) associated with of the scheduling Outbox being targeted by the request;
• (CALDAV:recipient-specified): The POST request MUST include one or more valid Recipient request headers specifying the calendar user address of users to whom the scheduling message will be delivered.

Postconditions: None¶

Incoming scheduling messages will be stored in a scheduling Inbox collection. As per Section 9, CalDAV calendar access reports work on scheduling collections, so the client can use those to get partial information on scheduling messages in the scheduling inbox.¶

Scheduling messages are delivered into a recipients Inbox collection. To process these messages a calendar user agent client needs to follow a sequence of steps to ensure good interoperability with other clients that may also be monitoring or processing the Inbox.¶

Processing a scheduling message in an Inbox collections requires the client to read the message, determine the nature of the scheduling operation, make appropriate adjustments to the recipients actual calendars, and then, if required, send a response.¶

In order to ensure that only one client at a time is processing scheduling messages in an Inbox collection, clients MUST use the WebDAV locking feature to lock the entire Inbox collection for the duration of its processing step. Once a collection is locked, other clients attempting to obtain their own lock will fail as the WebDAV server will return a protocol error at that point. Clients MUST NOT attempt to process scheduling messages in an Inbox without having obtained a lock first.¶

When a scheduling message has been processed by a client it MUST delete that message from the Inbox before removing the webDAV lock on the Inbox collection. This ensures that other clients will not in the future attempt to process the scheduling message again.¶

TODO: provide definitions of new iCalendar parameters RECEIVED-DTSTAMP and RECEIVED-SEQUENCE that will help with schedule processing.¶

The Originator request header value is a URI which specifies the calendar user address of the originator of the scheduling message. Note that the absoluteURI production is defined in RFC2396 [RFC2396].¶

The Recipient request header value is a URI which specifies the calendar user address of the recipients to which the POST method should deliver the submitted scheduling message. Note that the absoluteURI production is defined in RFC2396 [RFC2396] ¶

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

This section defines new properties for WebDAV principal resources as defined in RFC3744 [RFC3744]. These properties are likely to be protected but the server MAY allow them to be written by appropriate users.¶

Name:

schedule-response

Namespace:

urn:ietf:params:xml:ns:caldav

Purpose:

Contains the set of responses for a POST method request.

Description:

See Section 6.1.4.

Definition:

                
    <!ELEMENT schedule-response (response*)>
            
              

Name:

response

Namespace:

urn:ietf:params:xml:ns:caldav

Purpose:

Contains a single response for a POST method request.

Description:

See Section 6.1.4.

Definition:

<!ELEMENT response (recipient,
                    request-status,
                    calendar-data?,
                    DAV:error?,
                    DAV:responsedescription?)>
              

Name:

recipient

Namespace:

urn:ietf:params:xml:ns:caldav

Purpose:

The calendar user address (recipient header value) that the enclosing response for a POST method request is for.

Description:

See Section 6.1.4.

Definition:

                
    <!ELEMENT recipient (#PCDATA)>
            
              

Name:

request-status

Namespace:

urn:ietf:params:xml:ns:caldav

Purpose:

The iTIP REQUEST-STATUS property value for this response.

Description:

See Section 6.1.4.

Definition:

                
    <!ELEMENT request-status (#PCDATA)>
            
              

When handling a POST request on a scheduling Outbox: ¶

• Servers MUST verify that the principal associated with the calendar user address specified in the Originator request header in the request matches the currently authenticated user.
• Servers MUST verify that the currently authenticated user has the CALDAV:schedule privilege or a suitable sub-privilege on the scheduling Outbox targeted by the request.
• Servers MUST verify that the principal associated with the calendar user address specified in the ORGANIZER property of the scheduling message data in the request contains a CALDAV:schedule-outbox-URL property value that matches the scheduling Outbox targeted by the request.
• Servers MUST verify that the principal associated with the calendar user address specified in the ORGANIZER property of the scheduling message data in the request has the CALDAV:schedule privilege or a suitable sub-privilege on all of the scheduling Inbox collections for the principals associated with all of the calendar user addresses specified in any Recipient request headers in the request.
• The CALDAV:calendar-free-busy-set property on principal resources SHOULD only be accessible when that principal is authenticated (i.e., the property SHOULD be hidden from other principals).

14.1. Normative References

[I-D.dusseault-caldav]

Dusseault, L., “Calendaring Extensions to WebDAV (CalDAV)”, Internet-Draft draft-dusseault-caldav-15 (work in progress), September 2006.

[RFC2119]

Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997.

[RFC2246]

Dierks, T. and C. Allen, “The TLS Protocol Version 1.0”, RFC 2246, January 1999.

[RFC2396]

Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifiers (URI): Generic Syntax”, RFC 2396, August 1998.

[RFC2445]

Dawson, F., Stenerson, D., “Internet Calendaring and Scheduling Core Object Specification (iCalendar)”, RFC 2445, November 1998.

[RFC2446]

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.

[RFC2447]

Dawson, F., Mansour, S., and S. Silverberg, “iCalendar Message-Based Interoperability Protocol (iMIP)”, RFC 2447, November 1998.

[RFC2518]

Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. Jensen, “HTTP Extensions for Distributed Authoring -- WEBDAV”, RFC 2518, February 1999.

[RFC2616]

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.

[RFC2818]

Rescorla, E., “HTTP Over TLS”, RFC 2818, May 2000.

[RFC3744]

Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, “Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol”, RFC 3744, May 2004.

[RFC4346]

Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.1”, RFC 4346, April 2006.

[W3C.REC-xml-20060816]

Bray, T., Paoli, J., Maler, E., Sperberg-McQueen, C., and F. Yergeau, “Extensible Markup Language (XML) 1.0 (Fourth Edition)”, World Wide Web Consortium Recommendation REC-xml-20060816, August 2006, <http://www.w3.org/TR/2006/REC-xml-20060816>.

14.2. Informative References

[I-D.ietf-webdav-rfc2518bis]

Dusseault, L., “HTTP Extensions for Distributed Authoring - WebDAV”, Internet-Draft draft-ietf-webdav-rfc2518bis-18 (work in progress), February 2007.

1. Added free-busy example.
2. Better abstract.
3. Requiring DAV level 2 for locking of Inbox.
4. Do not require servers to actually save Outbox requests.
5. Removed CALDAV:schedule-state Property. Clients now must remove inbox items after processing them, using locking etc to prevent race conditions.
6. Switched back to 2518 reference from 2518bis.
7. Updated to more recent XML reference.
8. Revised required features section to better match caldav-access.

1. Split schedule privilege into three sub-privileges.
2. Made support for caldav-access optional.
3. Changed SCHEDULE method to POST.

1. Updated to latest references including 2518bis.
2. Added principal property CALDAV:calendar-user-address-set.
3. Major changes to schedule method, including addition of preconditions.
4. New principal properties added.
5. Text related to alternative ways of doing scheduling (some speculative) removed.
6. Added Security Considerations text.
7. Added IANA consideration text.