From RFC 6321 (xCal), read in full from rfc-editor.org, including the relax-NG schema of its appendix A, which the RFC
calls non-normative. Every name is in the namespace urn:ietf:params:xml:ns:icalendar-2.0; the RFC writes
IC: before an element name to say so. The iCalendar side is on the
components and properties and
values and parameters pages.
Structure elements
| Element | Holds | iCalendar |
|---|---|---|
icalendar | one or more vcalendar | the iCalendar stream (RFC 5545 3.4) |
vcalendar | properties, then components | BEGIN:VCALENDAR to END:VCALENDAR |
properties | the property elements of the component | the content lines of the component that are not components |
components | the sub-component elements | the nested BEGIN to END blocks |
parameters | the parameter elements of one property; left out when there are none | the ;NAME=value parts of a content line |
Components
A component is an element with the component's name in lower case (RFC 6321 section 3.3). New components added to iCalendar later are converted the same way. The schema allows the sub-components shown.
| Component | Element | Sub-components in the schema |
|---|---|---|
VCALENDAR | vcalendar | vevent, vtodo, vjournal, vfreebusy, vtimezone |
VEVENT | vevent | valarm |
VTODO | vtodo | valarm |
VJOURNAL | vjournal | none |
VFREEBUSY | vfreebusy | none |
VTIMEZONE | vtimezone | standard, daylight (at least one of them) |
STANDARD, DAYLIGHT | standard, daylight | none |
VALARM | valarm | none |
Properties
A property is an element with the property's name in lower case (section 3.4); an extension property X-FOO
is x-foo in the same namespace (section 3.7). The value elements are the ones the schema of appendix A
gives; + means one or more.
| Property | Value elements | Parameters in the schema |
|---|---|---|
CALSCALE | text (GREGORIAN) | none |
METHOD, PRODID | text | none |
VERSION | text (2.0) | none |
ATTACH | uri or binary | fmttype, encoding |
CATEGORIES, RESOURCES | text+ | language (resources: also altrep) |
CLASS | text (PUBLIC, PRIVATE, CONFIDENTIAL) | none |
COMMENT, DESCRIPTION, LOCATION, SUMMARY | text | altrep, language |
GEO | latitude and longitude, each a float (not value-type elements) | none |
PERCENT-COMPLETE, PRIORITY, REPEAT, SEQUENCE | integer | none |
STATUS | text (events: TENTATIVE, CONFIRMED, CANCELLED; to-dos: NEEDS-ACTION, COMPLETED, IN-PROCESS, CANCELLED; journals: DRAFT, FINAL, CANCELLED) | none |
COMPLETED, CREATED, DTSTAMP, LAST-MODIFIED | date-time | none |
DTEND, DTSTART, DUE | date-time or date | tzid |
DURATION | duration | none |
FREEBUSY | period+ | fbtype |
TRANSP | text (OPAQUE, TRANSPARENT) | none |
TZID | text | none |
TZNAME | text | language |
TZOFFSETFROM, TZOFFSETTO | utc-offset | none |
TZURL, URL | uri | none |
ATTENDEE | cal-address | cutype, member, role, partstat, rsvp, delegated-to, delegated-from, sent-by, cn, dir, language |
CONTACT | text | altrep, language |
ORGANIZER | cal-address | cn, dir, sent-by, language |
RECURRENCE-ID | date-time or date | tzid, range |
RELATED-TO | text | reltype |
UID | text | none |
EXDATE | date-time+ or date+ | tzid |
RDATE | date-time+, date+ or period+ | tzid |
RRULE | recur | none |
ACTION | text (AUDIO, DISPLAY, EMAIL) | none |
TRIGGER | duration (with the related parameter) or date-time | related |
REQUEST-STATUS | code, description and optionally data, each text (section 3.4.1.3: data is left out when empty) | language |
The multi-valued properties of section 3.4.1.1 are CATEGORIES, RESOURCES,
FREEBUSY, EXDATE and RDATE: one value element for each value of the comma-separated list.
Parameters
A parameter is an element with the parameter's name in lower case inside parameters (section 3.5). It holds
one or more value elements, never plain text. VALUE has no element (section 3.5.1).
| Parameter | Element | Content |
|---|---|---|
ALTREP, DIR | altrep, dir | uri |
CN, FMTTYPE, LANGUAGE, TZID | cn, fmttype, language, tzid | text |
CUTYPE | cutype | text: INDIVIDUAL, GROUP, RESOURCE, ROOM, UNKNOWN |
DELEGATED-FROM, DELEGATED-TO, MEMBER | delegated-from, delegated-to, member | cal-address+ |
ENCODING | encoding | text: 8BIT, BASE64 |
FBTYPE | fbtype | text: FREE, BUSY, BUSY-UNAVAILABLE, BUSY-TENTATIVE |
PARTSTAT | partstat | text: NEEDS-ACTION, ACCEPTED, DECLINED, TENTATIVE, DELEGATED; for to-dos also COMPLETED, IN-PROCESS |
RANGE | range | text: THISANDFUTURE |
RELATED | related | text: START, END |
RELTYPE | reltype | text: PARENT, CHILD, SIBLING |
ROLE | role | text: CHAIR, REQ-PARTICIPANT, OPT-PARTICIPANT, NON-PARTICIPANT |
RSVP | rsvp | boolean |
SENT-BY | sent-by | cal-address |
an unrecognised or X- parameter | its lower-case name | unknown, the text of the value treated as text (section 5) |
Value elements
A value type is an element with its name in lower case (section 3.6). Dates and times use the XML Schema forms, with
hyphens and colons, and no UTC offset: a zone is given by the tzid parameter, as in iCalendar.
| Type | Element | Content | Example |
|---|---|---|---|
| BINARY | binary | base64 (RFC 4648 section 4); white space may be added and is removed on the way back | SGVsbG8gV29ybGQh |
| BOOLEAN | boolean | xsd:boolean | true |
| CAL-ADDRESS | cal-address | a URI | mailto:cyrus@example.com |
| DATE | date | YYYY-MM-DD | 2011-05-17 |
| DATE-TIME | date-time | YYYY-MM-DDTHH:MM:SS with an optional Z | 2011-05-17T12:00:00 |
| DURATION | duration | as in RFC 5545 | P1D |
| FLOAT | float | xsd:float | 0.5 |
| INTEGER | integer | xsd:integer | -100 |
| PERIOD | period | start (a date-time), then end (a date-time) or duration | <start>2011-05-17T12:00:00</start><duration>P1H</duration> |
| RECUR | recur | one child for each rule part (below) | <freq>YEARLY</freq><count>5</count> |
| TEXT | text | the text with its escapes taken off; a line feed is a character | Hello World! |
| TIME | time | HH:MM:SS with an optional Z | 12:00:00 |
| URI | uri | a URI | http://calendar.example.com |
| UTC-OFFSET | utc-offset | +HH:MM or -HH:MM, with optional :SS | -05:00 |
| (not known) | unknown | the unprocessed value text; no VALUE parameter on the way back | 20110512T120000Z |
Recurrence rule parts
The children of recur, in the order the schema lists them: freq (SECONDLY, MINUTELY, HOURLY,
DAILY, WEEKLY, MONTHLY, YEARLY), then until (a date or date-time) or count, then
interval, then any number of bysecond, byminute, byhour,
byday (an optional integer and SU, MO, TU, WE, TH, FR or SA), bymonthday,
byyearday, byweekno, bymonth and bysetpos (one element for each value),
then wkst. The text form FREQ=YEARLY;COUNT=5;BYDAY=-1SU;BYMONTH=10 is
<freq>YEARLY</freq><count>5</count><byday>-1SU</byday><bymonth>10</bymonth>.
Conversion rules
iCalendar to xCal (RFC 6321 section 3)
- Unfold all lines first. Remove the backslash escapes of text values and the escaping of parameter values.
ENCODING=BASE64: for a BINARY value keep the base64; for any other value type remove the parameter and base64-decode the value.- Names of components, properties and parameters become lower case. The
VALUEparameter is skipped. - Any property without
VALUEwhose default type is not known is written withunknown; so is any unrecognised parameter value.
xCal to iCalendar (RFC 6321 section 4)
- Names SHOULD be converted to upper case. Text is backslash-escaped, and lines folded, as RFC 5545 requires. Non-binary values MUST NOT be base64 encoded.
VALUEMUST be written when the value type is not the property's default type. Forunknownit MUST NOT be.- An element in the iCalendar namespace whose name begins
x-becomes the extension property. An element in another namespace that is a direct child ofpropertiesSHOULD be kept in anXMLproperty (section 4.2; its value is one XML element with a namespace declaration, and it MUST NOT be in the iCalendar namespace); other elements are ignored.
What the viewer reports
- a root that is not
icalendarin the namespace, a child of it that is notvcalendar, a component with an element other thanpropertiesandcomponents, or more than one of either; - a property with no value element, with value elements of different types, with a type that is not a value type, or whose type the property does not take;
- a value whose text does not have the form of its type (a date with no hyphens, a time without seconds, a boolean that is not true, false, 1 or 0, an offset without a colon);
- a
geowithoutlatitudeandlongitude, arequest-statuswithoutcodeanddescription, aperiodwithout a start or without an end or duration, a rule part the schema does not have,freqmissing,untilandcounttogether; - an empty
parameterselement, a parameter holding text where a value element belongs, a parameter whose value element is not the one the schema gives, avalueparameter; - a property element holding text directly (RFC 6321's own second example does this with
tzid); - every problem the iCalendar viewer finds in the converted text, at the element that made the line.