Introduction
xCal is iCalendar written as XML. It is defined by RFC 6321 (August 2011) as a
one-to-one mapping: every component, property, parameter and value of an iCalendar object has an element, so
converting to xCal and back gives the same calendar. The file extension is .xcs and the media
type is application/calendar+xml (RFC 6321 section 7.2). Everything is in the namespace
urn:ietf:params:xml:ns:icalendar-2.0.
xCal is a separate format from iCalendar, not a variant of it: the data model is the same, but the syntax, the
files, the media type and the way each value is written are different. The mapping page lists them.
The explorer opens a .xcs file, and a .xml file or one with no extension whose
root element is icalendar in that namespace, in the xCal viewer.
Structure
The root element icalendar is the iCalendar stream. It holds one or more vcalendar
elements, one for each iCalendar object. A component element (vcalendar, vevent,
vtimezone, valarm and so on) holds one properties element, then one
components element for its sub-components. A property is an element with the property's name in lower
case. It holds an optional parameters element (left out when there are no parameters), whose children
are the parameters, each holding value elements; then one or more value elements named after the value type:
text, date-time, duration, recur and the rest. There is no
VALUE parameter: the value element says the type.
0<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0"> the streamroot…<vcalendar> one iCalendar object1 or more…<properties> prodid, version, calscale, method1…<components> vevent, vtodo, vjournal, vfreebusy, vtimezone1
<dtstart><parameters><tzid><text>…</text></tzid></parameters><date-time>…</date-time></dtstart>.The same event in both forms (RFC 6321 appendix B.1):
BEGIN:VEVENT
DTSTAMP:20080205T191224Z
DTSTART:20081006
SUMMARY:Planning meeting
UID:4088E990AD89CB3DBB484909
END:VEVENT
<vevent><properties>
<dtstamp><date-time>2008-02-05T19:12:24Z</date-time></dtstamp>
<dtstart><date>2008-10-06</date></dtstart>
<summary><text>Planning meeting</text></summary>
<uid><text>4088E990AD89CB3DBB484909</text></uid>
</properties></vevent>
The RFC's iCalendar text has DTSTART:20081006. Because the value is a date and the default type of
DTSTART is date-time, RFC 5545 needs DTSTART;VALUE=DATE:20081006, which is what the
conversion from the XML gives.
Converting
- iCalendar to xCal (RFC 6321 section 3): unfold the lines, remove the escaping of text and
parameter values, write names in lower case, drop the
VALUEparameter and name the value type by its element, write dates and times in the XML Schema forms (2011-05-17T12:00:00Z), and write the structured values (RRULE, PERIOD, GEO, REQUEST-STATUS) as child elements. A property or parameter whose type is not known gets the value elementunknownwith the raw text. - xCal to iCalendar (RFC 6321 section 4): names in upper case, text escaped, lines folded at 75
octets,
VALUE=added when the type is not the property's default, and a property whose value isunknownwritten withoutVALUE. Elements in another namespace may be kept in anXMLproperty. The element mapping page has the details.
The viewer does this conversion and reads the resulting iCalendar text with the iCalendar viewer, so the Events, Repeats and Time zones tabs work; its Mapping tab sets each element against the content line it becomes.
Not described
The pages follow RFC 6321, read in full from rfc-editor.org (the text, the relax-NG schema of appendix A and both examples). The element mapping page has every component, property, parameter and value element of the schema.
Known, not yet covered
- Viewer: the XML is read with the explorer's XML reader (its tree, its Text tab and its
well-formedness problems), then each element is checked against the schema's elements, the value syntax of each type
and the rules of RFC 6321 sections 3 to 5, and the whole is converted to iCalendar text and read by the iCalendar
viewer, whose problems are shown at the element that made each line. Not done: the schema's element order and
cardinalities are not checked as such (the iCalendar viewer checks the required properties and the counts on the
converted text); an element in another namespace is reported and left out, not converted to an
XMLproperty (RFC 6321 section 4.1); properties added after RFC 6321 (RFC 7986, 9073 and others) have no schema in the RFC, so their value types are taken from the iCalendar viewer's table; a file over 24 MiB is shown as XML only. - Reference: the XML Schema datatypes the schema cites (xsd:float, xsd:boolean and so on) are described by their lexical forms in the mapping page, not from the XML Schema Part 2 text.
Unknown
- Reference: RFC 6321's schema is stated to be non-normative and has errors: the time zone component names
property-tzuurlwhere it definesproperty-tzurl, andtype-untilusestype-dateandtype-date-time, which it never defines. No erratum list was read.
Also used for
- Extensible Markup Language – Nested elements with tags and attributes, written as text.
- xCard: vCard in XML – vCard 4.0 contacts as XML: names, numbers and addresses as elements.
Links
Developers
- biweekly – iCalendar library with xCal and jCal support (Java)
- sabre/vobject – reads and writes iCalendar and vCard, including their XML and JSON forms (PHP)