Collected Extensions to CalDAV

Collected Extensions to CalDAV Apple Inc.

1 Infinite Loop Cupertino CA 95014 USA cyrus@daboo.name http://www.apple.com/

Applications CalDAV calendaring iCalendar This document defines a set of extensions to the CalDAV calendar access protocol.

defines the CalDAV Calendar Access protocol for accessing calendar data stored on a server. With the popularity of CalDAV increasing, a number of useful extensions have been proposed to improve the protocol. This specification collects several of those extensions into one document for convenience. Each extension defined in this specification can be implemented independently of any of the others. Discussion of this Internet-Draft is taking place on the mailing list <https://www.ietf.org/mailman/listinfo/caldav>.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in . Other notations used in this memo follow the notations of .

The CALDAV:calendar-query report defined in Section 7.8 of allows a client to search calendar data for a match to iCalendar component, property or parameter details. As defined, this option supports querying multiple attributes of the iCalendar data at various "nesting" levels based on the syntactic structure of iCalendar itself. When multiple attributes are queried at the same level, each has to match for the query to be successful - effectively defining a logical "and" operation. This does not allow clients to execute a single query to match different attributes of different component types (e.g., clients cannot search for VEVENTs with a particular time-range, or VTODOs that are not completed). Since there is a need to be able to execute such queries, a logical "or" operation is needed. This specification adds a "test" XML attribute to the CALDAV:comp-filter and CALDAV:prop-filter XML elements that accepts values of "allof" or "anyof" to indicate logical "and" or "or" operations respectively. This copies the behavior defined for CARDDAV:addressbook-query reports defined in Section 10.5 of , with the exception that the default value for the attribute is "allof" to match the current behavior. The text comparison operation in is a simple "contains" operation, however more sophisticated comparisons are sometimes needed (e.g., 'starts with', 'equals', etc). This specification adds a "match-type" XML attribute to the CALDAV:text-match XML element that accepts values of "equals", "contains", "starts-with", or "ends-with", to indicate the comparison operation to be used. This copies the behavior defined for CARDDAV:addressbook-query reports defined in Section 10.5.4 of . Sometimes clients want to search all component types for a match (e.g., clients cannot find all calendar object resources that contain a SUMMARY property value matching some text irrespective of the top-level component type). This specification allows the use of a single "*" character in the "name" attribute of "comp-filter" elements to require the server to match any component type. Servers advertise support for this extension by including the token "calendar-query-extended" in the DAV response header to an OPTIONS request on any resource supporting the extended query report. Clients MUST check for the presence of that token before using the "test" or "match-type" XML attributes. This specification extends the XML syntax for the CALDAV:comp-filter, CALDAV:prop-filter and CALDAV:text-match XML elements as follows.

CALDAV:comp-filter

]]> The "test" attribute specifies whether any (logical OR) or all (logical AND) of the is-not-defined, time-range, comp-filter or param-filter tests need to match in order for the overall filter to match.

CALDAV:prop-filter

]]> The "test" attribute specifies whether any (logical OR) or all (logical AND) of the is-not-defined, time-range, text-filter or param-filter tests need to match in order for the overall filter to match.

CALDAV:text-match

]]> The "match-type" attribute is used to indicate the type of match operation to use. Possible choices are: "equals" - an exact match to the target string "contains" - a substring match, matching anywhere within the target string "starts-with" - a substring match, matching only at the start of the target string "ends-with" - a substring match, matching only at the end of the target string

In this request, the client is querying for VEVENTs that start on or after a specific date, or VTODOs that are not completed and not cancelled.

CANCELLED

]]>

In this request, the client is querying for any component that contains a VALARM sub-component.

]]>

CalDAV supports the notion of calendar collections that are restricted to only containing components of a certain type, or set of types. The protocol allows clients to specify the restricted component sets by supplying a CALDAV:supported-calendar-component-set WebDAV property in an MKCALENDAR or extended MKCOL request that creates a calendar collection. However, servers themselves might need to restrict the allowed sets of components that can be used in any one calendar (e.g., some servers might only support calendar collections containing components of one type). Currently there is no way for a client to determine what the allowed combination of component types is for use with MKCALENDAR or extended MKCOL. This specification adds a new CALDAV:supported-calendar-component-sets WebDAV property for use on calendar home collections. This property enumerates the allowed sets of calendar components that the server will support for use with MKCALENDAR or extended MKCOL requests. Clients SHOULD check for the presence of this property before issuing an MKCALENDAR or extended MKCOL request that includes a CALDAV:supported-calendar-component-set WebDAV property. When the new property is found on a calendar home, clients MUST only use a CALDAV:supported-calendar-component-set is one advertised as being supported.

supported-calendar-component-sets urn:ietf:params:xml:ns:caldav Enumerates the sets of component restrictions the server is willing to allow the client to specify in MKCALENDAR or extended MKCOL requests. This property MUST be protected and SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of ). This property value MUST be preserved in COPY and MOVE operations. If servers apply restrictions on the allowed calendar component sets used when creating a calendar, then those servers SHOULD advertise this property on each calendar home collection within which the restrictions apply. In the absence of this property, clients cannot assume anything about whether the server will enforce a set of restrictions or not - in that case clients need to handle the server rejecting certain combinations of restricted component sets. If this property is present, but contains no child XML elements, then clients can assume that the server imposes no restrictions on the combinations of component types it is willing to accept. If present, each CALDAV:supported-calendar-component-set element represents a valid restriction the client can use in an MKCALENDAR or extended MKCOL request when creating a calendar.

]]>

Calendar clients are sometimes "scoped" to only utilize one type of main calendar component type (e.g., a scheduling client that only handles "VEVENT" components, or a task manager that only handles "VTODO" components). CalDAV provides a calendar query report that allows clients to find only calendar object resources that contain a specified main component type, which is useful when initially loading the contents of a calendar into a local cache. However, clients also need to keep that cache updated as changes occur on the server. One way to do that is to use the WebDAV sync report, but that report will return changes for all calendar object resources within a calendar collection. Thus "scoped" clients will be forced to load calendar object resources containing component types they do not care about to discover what type they are, or issue additional queries to see whether the changes reported by the sync report are for component types it handles. A better approach would be to have a way for the WebDAV sync report response to include details of the calendar component type for each calendar object resource that it reports as changed. To better "scope" a WebDAV sync report, this specification recommends that servers SHOULD always include a "component=" parameter (as defined in Section 8.1 of ) in the DAV:getcontenttype WebDAV property media-type value reported for calendar object resources. Clients can then request that property be returned in the WebDAV sync report response for each resource, and thus quickly determine which changes are relevant to them based on component type.

Example partial WebDAV sync report response with a component type included. http://calendar.example.com/cyrusdaboo/calendar.ics "00003-abcd1" text/calendar;charset=utf-8;component=vevent< /D:getcontenttype> HTTP/1.1 200 OK ]]>

This specification does not introduce any new security concerns beyond those addressed in CalDAV and iCalendar.

No IANA actions are needed.

Thanks to Bernard Desruisseaux, Mike Douglass, Jeffrey Harris, Arnaud Quillaud, and Nick Zitzmann. This specification came about via discussions at the Calendaring and Scheduling Consortium.

&rfc2119; &rfc4791; &rfc4918; &rfc5545; &rfc5689; &idWebDAVSync; &rfc6352;

Changes in -01: Changed description of COPY/MOVE for supported-calendar-component-sets property Removed bogus text in property description. Changed supported-calendar-component-sets to use supported-calendar-component-set as a child element. Added recommendation to use "component=" parameter in DAV:getcontenttype WebDAV properties on calendar object resources.