CalDAV draft

Proposal for Mapping iCalendar Properties to WebDAV Properties

Approach

The intent of mapping iCalendar properties to WebDAV properties is so that clients can choose either to download the entire iCalendar body of an event or task (containing all the information in iCalendar properties), or clients can choose to query or search on WebDAV properties using PROPFIND or SEARCH and see a subset or all of the same information. A client can use one or several of these techniques as appropriate and still interoperate with other clients.

The obvious mapping for iCalendar property names is to make the WebDAV property name the same string. That means we need to be able to map every legal iCalendar property name to a legal XML element name. Since iCalendar property names are nearly always legal XML element names only a minor transformation must be made (see below).

Since iCalendar parameter names follow the same character set rules as iCalendar property names, these can be mapped to XML attributes (which follow the same naming rules as XML elements). The choice of attributes means that the existing WebDAV SEARCH syntax can be used to search iCalendar property values, but it can't be used to search parameter values.

The value of iCalendar properties and parameters can then be mapped to XML text within the XML elements, with the simple transformation of escaping XML control characters.

WebDAV properties"> Namespaces for WebDAV properties

All iCalendar properties can be mapped to WebDAV properties in a single namespace. The namespace chosen is "urn:ietf:params:xml:ns:caldav:icalendar". Both standard iCalendar property names and x-names are in the same namespace.

This namespace is reserved only for WebDAV properties that can be transformed to iCalendar properties Thus,

• the property name MUST follow iCalendar property name rules,
• there MUST only be a flat list of elements within the property value, to be mapped to parameters,
• the names of elements to be mapped to parameters MUST follow the iCalendar parameter name rules, and
• the values MUST follow iCalendar value rules.

Mapping property and parameter names

The intent is to express each iCalendar property as a WebDAV property, and to express each iCalendar parameter as an XML attribute inside that WebDAV property. The mappings are reversible.

The names of iCalendar properties and parameters may be IANA tokens or x-names. The x-names must begin with "X-". Both x-names and IANA-registered tokens may only contain alphabetical characters, digits or the '-' character. The only case in which a iCalendar name would not automatically be a legal XML element or attribute name is when the iCalendar name begins with a digit, so in that case we prefix the attribute name with "_". Otherwise iCalendar names become legal XML element or attribute names without transformation.

iCalendar name	XML element or attribute name
VERSION	VERSION
X-ABC-MMSUBJ	X-ABC-MMSUBJ
X-EXA-411-ENTRY	X-EXA-411-ENTRY
411-ENTRY	_411-ENTRY

To make the reverse transformation possible, we need to be able to derive legal iCalendar property and parameter names out of any WebDAV property names in the "urn:ietf:params:xml:ns:caldav:icalendar" namespace and any XML attribute names on the property. Thus the WebDAV property or attribute names in that namespace MUST be legal iCalendar names, either as-is or after the removal of a leading underscore character. If the name begins with an underscore the underscore MUST be stripped during the transformation to iCalendar. Otherwise, elements in this namespace MUST not contain the underscore character as that is not a legal character in iCalendar names.

iCalendar values

In single-valued properties, the property value and any parameter values are transformed to XML Text to appear inside the appropriate element. In the transformation from iCalendar value to XML Text:

• First the iCalendar value must be unfolded (line returns followed by a single

whitespace must be removed)

• If the value contains any ampersand, greater-than and less-than characters ,

these MUST all be escaped or the ENTIRE value MUST be encapsulated.

• The value MAY be encapsulated even if it doesn't contain special characters.

In the reverse transformation from XML Text to iCalendar value:

• The value MUST be unencapsulated, or if that's not possible, then unescaped.

The transformation MUST NOT undo more than one escaping or encapsulation.

iCalendar value	XML text
Elephant & Castle	Elephant & Castle
Elephant & Castle	<![CDATA[Elephant & Castle]]>
Penticton>>Kelowna	Penticton>>Kelowna
Penticton>>Kelowna	<![CDATA[Penticton>>Kelowna]]>
Status meeting	Status meeting
Status meeting	<![CDATA[Status meeting]]>

Multiple values

iCalendar properties support multiple values whereas WebDAV properties support complex values (which may be interpreted as multiple values). We need to transform the multiple values to an XML fragment which can clearly be understood and transformed back to iCalendar multiple values. To do this, we add structure to the WebDAV property value so that each value is contained inside a 'value' element in the 'urn:ietf:params:xml:ns:caldav' namespace. The entire value, including parameters for that value, are contained inside the 'value' element.

Ordering

There is no ordering implied for properties within an iCalendar object, nor for WebDAV properties on a WebDAV resource. There is no ordering implied for multiple values on either side. Although this isn't stated unambiguously in the iCalendar specification, it is common implementation practice for there to be no ordering implied for parameters on an iCalendar property.

Example

VEVENT and corresponding WebDAV property values

    BEGIN:VEVENT
     DTSTAMP:19980309T231000Z
     UID:guid-1.host1.com
     ORGANIZER;ROLE=CHAIR:MAILTO:mrbig@host.com
     ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT;CUTYPE=GROUP:
      MAILTO:employee-A@host.com
     ATTENDEE;RSVP=FALSE:MAILTO:employee-B@host.com
     DESCRIPTION:Project XYZ Review Meeting
     CATEGORIES:MEETING
     CREATED:19980309T130000Z
     SUMMARY:XYZ Project Review
     DTSTART;TZID=US-Eastern:19980312T083000
     DTEND;TZID=US-Eastern:19980312T093000
     LOCATION:Rooms 4350 & 4351
     END:VEVENT

<prop xmlns="DAV:"
      xmlns:i="urn:ietf:params:xml:ns:caldav:icalendar"
      xmlns:c="urn:ietf:params:xml:ns:caldav">
    <i:DTSTAMP>19980309T231000Z</i:DTSTAMP>
    <i:UID>guid-1.host1.com</i:UID>
    <i:ORGANIZER i:ROLE="CHAIR">MAILTO:mrbig@host.com</i:ORGANIZER>
    <i:ATTENDEE>
      <c:value i:RSVP="TRUE"
               i:ROLE="REQ-PARTICIPANT"
               i:CUTYPE="GROUP">MAILTO:employee-A@host.com</c:value>
      <c:value i:RSVP="FALSE">MAILTO:employee-B@host.com</c:value>
    </i:ATTENDEE>
    <i:DESCRIPTION><![CDATA[Project XYZ Review Meeting]]></i:DESCRIPTION>
    <i:CATEGORIES>MEETING</i:CATEGORIES>
    <i:CREATED>19980309T130000Z</i:CREATED>
    <i:SUMMARY>XYZ Project Review</i:SUMMARY>
    <i:DTSTART><i:TZID>US-Eastern</i:TZID>19980312T083000</i:DTSTART>
    <i:DTEND><i:TZID>US-Eastern</i:TZID> 19980312T093000</i:DTEND>
    <i:LOCATION>Rooms 4350 &amp; 4351</i:LOCATION>
</prop>

There are a few things to note in this example. The DESCRIPTION value was encapsulated even though that was unnecessary. The LOCATION value was escaped. The SUMMARY value was neither escaped nor encapsulated. Also note that the line breaks in the WebDAV fragment and the line folding of the first ATTENDEE value in the iCalendar side were chosen for readability, and other foldings or line breaks could have been chosen without changing the meaning of the fragments.

-- LisaDusseault - 29 Nov 2004