CalDAV Scheduling Extensions to WebDAV

While the scheduling features described in this specification are based on iTIP [RFC2446], some of its more complex features have deliberately not been implemented, in order to keep this specification simple. In particular, the following iTIP [RFC2446] features are not supported: ¶

• Sending scheduling messages with the scheduling methods "PUBLISH", "COUNTER", and "DECLINECOUNTER"
• Delegating an Event to another calendar user
• Changing the "Organizer"
• Forwarding to an uninvited calendar user

The goal of this specification is to provide the essential scheduling features needed, and it is anticipated that future extensions will be developed to address the more complex features if the demand arises.

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

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 HTTP [RFC2616]. Because this augmented BNF uses the basic production rules provided in Section 2.2 of HTTP [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.¶

Calendar user agent (CUA):

Software with which the calendar user communicates with a calendar service or local calendar store to access calendar information.

Calendar collection:

Same as CalDAV "calendar-access" [RFC4791].

Scheduling calendar collection:

Calendar collection that supports automatic scheduling transactions.

Basic calendar collection:

Calendar collections as defined in CalDAV "calendar-access" [RFC4791] are referred to as basic calendar collections. Scheduling calendar collections are not basic calendar collections.

Calendar object resource:

Same as CalDAV "calendar-access" [RFC4791].

Scheduling object resource:

Calendar object resource contained in a scheduling calendar collection for which the server will take care of sending scheduling messages and processing incoming scheduling messages on behalf of the owner of the calendar collection.

Organizer scheduling object resource:

Scheduling object resource owned by an "Organizer".

Attendee scheduling object resource:

Scheduling object resource owned by an "Attendee".

Automatic scheduling transaction:

Add, change or remove operations on a scheduling object resource in a scheduling calendar collection for which the server will deliver scheduling messages to other users.

Explicit scheduling request:

Scheduling requests targeted at a scheduling Outbox collection such as search for busy time information as well as refresh requests.

Scheduling message:

Calendar object resource that describes a scheduling transaction such as publish, schedule, reschedule, respond to scheduling requests, or cancel calendar components.

Scheduling Outbox collection:

Resource at which explicit scheduling requests can be targeted.

Scheduling Inbox collection:

A collection in which a recipient's incoming scheduling messages are delivered.

This specification introduces new collection resource types that are used for managing resources specific to scheduling, in addition to basic calendar object resources.¶

Scheduling operations can cause the delivery of a scheduling message into an "Organizer's" or "Attendee's" scheduling Inbox collection. In the former case the scheduling messages are replies or refresh requests from "Attendees", in the latter case the scheduling messages are requests, cancellations or additions from the "Organizer".¶

In some cases the server will automatically process the scheduling message, in other cases the scheduling message will be left for the client to process. In each case, the scheduling message in the scheduling Inbox collection is used as an indicator to the client that a scheduling operation has taken place.¶

An explicit scheduling request sends a scheduling message via an HTTP POST request targeted at a scheduling Outbox collection. Full details can be found in Section 8.1.¶

Parameter Name:

SCHEDULE-AGENT

Purpose:

Indicates what agent is expected to handle scheduling for the corresponding "Attendee".

Format Definition:

This property parameter is defined by the following notation:

   scheduleagentparam = "SCHEDULE-AGENT" "="
                     ("SERVER"       ; The server handles scheduling
                    / "CLIENT"       ; The client handles scheduling
                    / "NONE"         ; No automatic scheduling
                    / x-name         ; Experimental type
                    / iana-token)    ; Other IANA registered
                                     ; type
   ; Default is SERVER
                 

Description:

This property parameter MAY be present on any "ATTENDEE" iCalendar property. In the absence of this parameter, the value "SERVER" MUST be used for the default behavior. The value determines whether or not an automatic scheduling transaction on a server will cause a scheduling message to be sent to the corresponding calendar user identified by the "ATTENDEE" property value. When the value "SERVER" is specified (or the parameter is absent) then it is the server's responsibility to send a scheduling messages as part of an automatic scheduling transaction. When the value "CLIENT" is specified, that indicates that the client is handling scheduling messages with the calendar user itself. When "NONE" is specified, no scheduling messages are being sent to the calendar user.

Servers MUST NOT include this parameter in any scheduling messages sent as the result of an automatic scheduling transaction.

Clients SHOULD NOT include this parameter in any scheduling messages that they themselves send.

Example:

   ATTENDEE;SCHEDULE-AGENT=SERVER:mailto:cyrus@example.org
                 

Parameter Name:

SCHEDULE-STATUS

Purpose:

Indicates the status code returned from processing of the most recent scheduling message sent to the corresponding "Attendee", or received from the corresponding "Organizer".

Format Definition:

This property parameter is defined by the following notation:

   schedulestatusparam = "SCHEDULE-STATUS" "=" statcode
   ; statcode defined in RFC2445.
                 

Description:

This property parameter may be present on any "ATTENDEE" or "ORGANIZER" iCalendar property.

Servers MUST add this parameter to any "ATTENDEE" properties corresponding to calendar users who were sent a scheduling message via an automatic scheduling transaction. Clients SHOULD NOT change or remove this parameter if it was provided by the server. In the case where the client is handling the scheduling the client MAY add, change or remove this parameter to indicate the last scheduling message status it received.

Servers MUST add this parameter to any "ORGANIZER" properties corresponding to calendar users who were sent a scheduling message reply by an "Attendee" via an automatic scheduling transaction. Clients SHOULD NOT change or remove this parameter if it was provided by the server. In the case where the client is handling the scheduling the client MAY add, change or remove this parameter to indicate the last scheduling message status it received.

Servers MUST NOT include this parameter in any scheduling messages sent as the result of an automatic scheduling transaction.

Clients SHOULD NOT include this parameter in any scheduling messages that they themselves send.

Suitable values for this property parameter are described in Section 3.5.4.

Example:

   ATTENDEE;SCHEDULE-STATUS="2.0":mailto:cyrus@example.org
                 

When an HTTP DELETE request occurs on a scheduling object resource, and the Schedule-Reply header is not present, or present and set to the value "T", the server MUST send an appropriate iTIP "CANCEL" scheduling message as part of its normal automatic scheduling transaction processing.¶

When an HTTP DELETE request occurs on a scheduling object resource, and the Schedule-Reply header is set to the value "F", the server MUST NOT send an iTIP scheduling message as part of its normal automatic scheduling transaction processing.¶

The Schedule-Reply request header is used by a client to indicate to a server whether or not an automatic scheduling transaction should occur when an "Attendee" deletes a scheduling object resource. In particular it controls whether an iTIP "CANCEL" message is sent to the "Organizer" as a result of the deletion. There are situations in which unsolicited scheduling messages need to be silently deleted (or ignored) for security or privacy reasons. The new header allows the scheduling message to be suppressed if such a need arises.¶

All scheduling object resources MUST support the Schedule-Reply header.¶

Name:

schedule-calendar-transp

Namespace:

urn:ietf:params:xml:ns:caldav

Purpose:

Determines whether the calendar object resources in a calendar collection will affect the owner's freebusy.

Protected:

This property MAY be protected and SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of WebDAV [RFC4918]).

COPY/MOVE behavior:

This property value SHOULD be kept during a MOVE operation, but is normally re-initialized when a resource is created with a COPY. It should not be set in a COPY.

Description:

This property SHOULD be defined on all calendar object resources. If present, it contains one of two XML elements that indicate whether the calendar object resources should contribute to the owner's freebusy or not. When the 'opaque' element is used, all calendar object resources MUST contribute to freebusy, assuming access privileges and other iCalendar properties allow it to. When the 'transparent' XML element is used, all calendar object resources MUST NOT contribute to freebusy.

Definition:

<!ELEMENT schedule-calendar-transp (opaque|transparent) >

<!ELEMENT opaque      EMPTY>
<!-- Calendar object resources affect owner freebusy -->

<!ELEMENT transparent EMPTY>
<!-- Calendar object resources never affect owner freebusy -->
                   

Example:

<C:schedule-calendar-transp
     xmlns:C="urn:ietf:params:xml:ns:caldav">
  <C:opaque/>
</C:schedule-calendar-transp>
                   

Name:

schedule-default-calendar-URL

Namespace:

urn:ietf:params:xml:ns:caldav

Purpose:

Specifies a default calendar for an attendee that will automatically have new scheduling messages deposited into it when they arrive.

Protected:

This property MAY be protected in the case where a server supports only a single scheduling calendar collection, or does not support changing the default calendar, or does not support a default calendar.

COPY/MOVE behavior:

This property is only defined on a scheduling Inbox collection which cannot be moved or copied.

Description:

This property MAY be defined on a scheduling Inbox collection. If present, it contains zero or one DAV:href XML elements. When a DAV:href element is present, its value indicates a URL to a scheduling calendar collection that is used as the default calendar. When no DAV:href element is present, it indicates that there is no default calendar. In the absence of this property there is no default calendar.

Definition:

<!ELEMENT schedule-default-calendar-URL (DAV:href?) >
                   

Example:

<C:schedule-default-calendar-URL xmlns:D="DAV:"
     xmlns:C="urn:ietf:params:xml:ns:caldav">
  <D:href>/calendars/users/cdaboo/calendar/</D:href>
</C:schedule-default-calendar-URL>
                   

Name:

schedule-state

Namespace:

urn:ietf:params:xml:ns:caldav

Purpose:

Indicates whether a scheduling message in a scheduling Inbox collection has been processed as part of an automatic scheduling transaction.

Protected:

This property MUST be protected as only the server can carry out automatic processing of scheduling messages.

COPY/MOVE behavior:

This property is only defined on a scheduling message in a scheduling Inbox collection. If a scheduling message is copied or moved into a scheduling Inbox collection, this property MUST NOT be set.

Description:

This property MAY be defined on a scheduling resource in a scheduling Inbox collection. If present, it contains one of two XML elements. When the CALDAV:schedule-unprocessed XML element is used, it indicates that the scheduling message has not been automatically processed by the server, and thus needs action on the part of the client. When the CALDAV:schedule-processed XML element is used, it indicates that automatic processing of the scheduling message has taken place, so no scheduling operations are needed by the client.

Definition:

<!ELEMENT schedule-state (schedule-processed|schedule-unprocessed) >

<!ELEMENT schedule-processed   EMPTY>
<!-- Scheduling message has been automatically processed -->

<!ELEMENT schedule-unprocessed EMPTY>
<!-- Scheduling message has not been automatically processed -->
                   

Example:

<C:schedule-state xmlns:C="urn:ietf:params:xml:ns:caldav">
  <C:schedule-processed/>
</C:schedule-state>
                   

This specification requires additional Preconditions for the PUT, COPY and MOVE methods. The preconditions are: ¶

• (CALDAV:unique-scheduling-object-resource): Only one scheduling object with a particular iCalendar property "UID" value MUST exist in the system for each "Organizer" and each "Attendee".
• (CALDAV:same-organizer-in-all-components): All the calendar components in a scheduling object resource being stored in a scheduling calendar collection MUST contain the same "ORGANIZER" property value if the "ORGANIZER" property is present.

This specification requires additional Preconditions for the PUT method. The preconditions are: ¶

• (CALDAV:allowed-organizer-scheduling-object-change): The following restrictions exist for the "PARTSTAT" property value in scheduling object resources created or modified by an "Organizer":
  1. when creating a scheduling object resource the "Organizer" MUST NOT set the "PARTSTAT" iCalendar parameter value to anything other than "NEEDS-ACTION" if the corresponding "ATTENDEE" property includes the "SCHEDULE-AGENT" iCalendar parameter with its value set to "SERVER".
  2. when modifying a scheduling object resource the "Organizer" MUST NOT change the "PARTSTAT" iCalendar parameter value to anything other than "NEEDS-ACTION" if the corresponding "ATTENDEE" property includes the "SCHEDULE-AGENT" iCalendar parameter with its value set to "SERVER".
• (CALDAV:allowed-attendee-scheduling-object-change): When creating or modifying a scheduling object resource in a scheduling calendar collection, the "Attendee" can only make the following changes:
  1. any iCalendar parameter on any "ATTENDEE" property whose value corresponds to the calendar user address of the "Attendee"
  2. add, change or remove a "TRANSP" property in any component
  3. add, change or remove a "COMMENT" property in any component
  4. add, change or remove a "PERCENT-COMPLETE" property in any component
  5. add, change or remove the "PRODID" property in the top-level "VCALENDAR" component
  6. add, change or remove the "CALSCALE" property in the top-level "VCALENDAR" component
  7. add, change or remove any "VALARM" components
  8. create overridden recurring instances with only changes as detailed above
  The "Attendee" MUST NOT make any other type of change.

This specification requires an additional Precondition for the property response elements in PROPPATCH method response. The precondition is: ¶

• (CALDAV:valid-schedule-default-calendar-URL): When the server allows the client to change the CALDAV:schedule-default-calendar-URL property on a scheduling Inbox collection, the URL specified in any DAV:href element MUST reference a scheduling calendar collection owned by the owner of the scheduling Inbox collection.

The POST method submits a scheduling or freebusy 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 freebusy 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 3.1.2).¶

Servers SHOULD reject any scheduling message that is not allowed. However, for backwards compatibility with earlier version of this specification, servers MAY return a valid schedule response result indicating success for the iTIP operation being executed.¶

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 (e.g., "text/calendar") for scheduling or freebusy messages;
• (CALDAV:valid-calendar-data): The resource submitted in the POST request MUST be valid data for the media type being specified (e.g., 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., the scheduling message follows the restrictions of iTIP);
• (CALDAV:originator-allowed): The currently authenticated user MUST be granted the CALDAV:schedule-deliver 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 the scheduling Outbox collection being targeted by the request when the scheduling message is an outgoing scheduling message;
• (CALDAV:max-resource-size): The resource submitted in the POST request MUST have an octet size less than or equal to the value of the CALDAV:max-resource-size property value [RFC4791]on the scheduling Outbox collection targeted by the request;
• (CALDAV:attachments-allowed): The resource submitted in the POST request MUST NOT contain any inline ATTACH properties;

Postconditions: None¶

Incoming scheduling messages will be stored in a scheduling Inbox collection. As per Section 10, 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 collection.¶

CalDAV servers MUST support and adhere to the requirements of WebDAV ACL [RFC3744]. Furthermore, CalDAV servers that advertise support for the "calendar-auto-schedule" feature MUST also support the scheduling privileges defined in this section.¶

All the scheduling privileges MUST be non-abstract and MUST appear in the DAV:supported-privilege-set property of scheduling Outbox and Inbox collections on which they are defined.¶

The tables specified in Appendix A clarifies which scheduling methods (e.g., "REQUEST" "REPLY" etc.) are controlled by each scheduling privilege 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 8.1.2.

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

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

Definition:

    <!ELEMENT recipient (DAV:href)>
            

Name:

request-status

Namespace:

urn:ietf:params:xml:ns:caldav

Purpose:

The iTIP "REQUEST-STATUS" property value for this response.

Description:

See Section 8.1.2.

Definition:

    <!ELEMENT request-status #PCDATA>
            

• Servers MUST verify that the currently authenticated user has the CALDAV:schedule-deliver privilege or a suitable sub-privilege on the scheduling Outbox collection of the DAV:owner of the scheduling calendar collection in which a scheduling object resource is being manipulated.
• Servers MUST verify that the principal associated with the DAV:owner of the scheduling calendar collection in which a scheduling object resource is being manipulated contains a CALDAV:schedule-outbox-URL property value.
• Servers MUST only deliver scheduling messages to recipients when the principal associated with the DAV:owner of the scheduling calendar collection in which a scheduling object resource is being manipulated has the CALDAV:schedule privilege or a suitable sub-privilege on the scheduling Inbox collections for recipient.
• To prevent impersonation of calendar users, the server MUST verify that the "ORGANIZER" property in an organizer scheduling object resource matches one of the calendar user addresses of the DAV:owner of the schedule calendar collection in which the resource is stored.
• To prevent spoofing of an existing scheduling object resource, servers MUST verify that the "UID" iCalendar property value in a new scheduling object resource does not match that of an existing scheduling object resource with a different "ORGANIZER" property value.

• Servers MUST verify that the currently authenticated user has the CALDAV:schedule-deliver privilege or a suitable sub-privilege on the scheduling Outbox collection 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 collection 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 those recipients to whom a scheduling message is being delivered.

This specification registers one new header for use with HTTP as per [RFC3864].¶

This specification registers two new iCalendar property parameters as defined in Section 4.¶

15.1. Normative References

[RFC2119]

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

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

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

[RFC3864]

Klyne, G., Nottingham, M., and J. Mogul, “Registration Procedures for Message Header Fields”, BCP 90, RFC 3864, September 2004.

[RFC4791]

Daboo, C., Desruisseaux, B., and L. Dusseault, “Calendaring Extensions to WebDAV (CalDAV)”, RFC 4791, March 2007.

[RFC4918]

Dusseault, L., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)”, RFC 4918, June 2007.

[W3C.REC-xml-20060816]

Maler, E., Paoli, J., Yergeau, F., Sperberg-McQueen, C., and T. Bray, “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>.

15.2. Informative References

[RFC2447]

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

The following tables specify which scheduling privileges grant the right to a calendar user to deliver a scheduling message to the scheduling Inbox collection of another calendar user. The appropriate behavior depends on the calendar component type in the scheduling message and the scheduling "METHOD" in use.¶

The following tables specify which scheduling privileges grant the right to a calendar user to submit a scheduling message to another calendar user, either as the result of an explicit scheduling request or an automatic scheduling transaction. The appropriate behavior depends on the calendar component type in the scheduling message and the scheduling "METHOD" in use.¶

This draft has changed substantially since the -04 version. The primary reason for this change was implementation experience from a number of vendors who implemented products based on the earlier drafts. Experience showed that the client/server interaction was not reliable in keeping scheduling messages synchronized between organizer and attendees. In addition the latency in updates due to clients being offline proved unacceptable to users. These issues led to the redesign of this specification to support a server-based processing model that eliminates all the problems seen previously. Whilst this adds significant complexity to the server in that it needs to be a full blown iTIP processing agent, it does remove a lot of the same complexity from clients, opening up the possibility of supporting complex scheduling behaviors even with "thin" clients.¶

In the judgement of the authors, we consider this new specification to be a substantial improvement over the old one and believe it represents a stronger protocol that will lead to better interoperability.¶