.ICS File Format – Extensions and other forms

Availability: VAVAILABILITY (RFC 7953)

Describes when a calendar user is available, with recurring "available" periods. The default over the period of a VAVAILABILITY is busy; AVAILABLE sub-components mark the free time inside it.

• Without DTSTART a VAVAILABILITY starts unbounded; without DTEND or DURATION it ends unbounded. DTSTART and DTEND in either component must be date-times, UTC or local with a time zone reference, and the object needs a VTIMEZONE for each TZID unless time zone references are by value (RFC 7809).
• BUSYTYPE: text, BUSY, BUSY-UNAVAILABLE (default), BUSY-TENTATIVE, or an IANA or X- value. The values are those of the FBTYPE parameter without FREE.
• Combining. PRIORITY orders overlapping components; a missing priority or 0 is the lowest, then 9 down to 1 (highest). Components of equal priority that overlap take the busy type in the order BUSY over BUSY-UNAVAILABLE over BUSY-TENTATIVE. To compute available time: order the intersecting components from lowest to highest priority, and for each mark its whole range busy and then free where its AVAILABLE parts are; a component that covers the whole range of interest makes the lower ones irrelevant. Spread priorities (0, 5, 7, 3 as in the RFC's example) so one can be inserted later.
• Free-busy. Start with the whole request period free; apply each intersecting VAVAILABILITY by priority (ignoring one wholly overridden), then overlay ordinary VEVENT and VFREEBUSY busy time.
• The RFC does not define use of VAVAILABILITY in iTIP; it adds a CalDAV calendar-availability feature (advertised in the DAV header) and rules for free-busy queries.

BEGIN:VAVAILABILITY
ORGANIZER:mailto:bernard@example.com
UID:0428C7D2-688E-4D2E-AC52-CD112E2469DF
DTSTAMP:20111005T133225Z
BEGIN:AVAILABLE
UID:34EDA59B-6BB1-4E94-A66C-64999089C0AF
SUMMARY:Monday to Friday from 9:00 to 17:00
DTSTART;TZID=America/Montreal:20111002T090000
DTEND;TZID=America/Montreal:20111002T170000
RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR
END:AVAILABLE
END:VAVAILABILITY

CalDAV scheduling parameters (RFC 6638)

RFC 6638 is mostly a WebDAV protocol (inbox and outbox collections, scheduling privileges, HTTP headers Schedule-Reply, Schedule-Tag and If-Schedule-Tag-Match); the parts that reach the file are three parameters on ORGANIZER and ATTENDEE:

The status codes are those of iTIP plus three delivery codes: 1.0 pending, 1.1 sent, 1.2 delivered. A server resets PARTSTAT of every Attendee except the Organizer to NEEDS-ACTION when a change to DTSTART, DTEND, DURATION, DUE, RRULE, RDATE or EXDATE affects existing instances.

ORGANIZER;SCHEDULE-AGENT=SERVER:mailto:bernard@example.com
ATTENDEE;SCHEDULE-AGENT=NONE:mailto:cyrus@example.com
ATTENDEE;SCHEDULE-STATUS="2.0,2.4":mailto:cyrus@example.com

Time zone data distribution (RFC 7808)

A service (HTTP GET requests, one per action, discovered by SRV records, TXT records and a well-known URI) that serves time zone data as iCalendar VTIMEZONE, or as iCalendar-in-XML or iCalendar-in-JSON. Its actions are capabilities, list, get, expand, find and leapseconds. Two properties are added to VTIMEZONE:

• TZUNTIL (0 or 1; DATE-TIME, UTC): an exclusive upper bound of the validity of the time zone data; a server also uses it for the end of a truncated range. Example TZUNTIL:20260101T000000Z.
• TZID-ALIAS-OF (0 or more; TEXT): the identifier of the time zone of which the component's TZID is an alias, for example TZID-ALIAS-OF:America/New_York in a zone called US/Eastern.

Concepts of the service: time zone identifiers are publisher-defined (no global naming scheme); aliases map a name to an identifier and may differ between truncated and untruncated data; localised names can be queried; data can be truncated to a range whose start is inclusive and end exclusive, both UTC, and the server must list the ranges it uses in its capabilities response. A truncated component starts with exactly one STANDARD or DAYLIGHT sub-component whose DTSTART is the start of the range and which has the offsets in effect just before and after it.

iCalendar in XML: xCal (RFC 6321)

Namespace urn:ietf:params:xml:ns:icalendar-2.0; media type application/calendar+xml (parameters method, component, optinfo and charset, UTF-8 strongly recommended).

• Before converting: unfold the lines and remove text and parameter escaping. A property with ENCODING=BASE64 keeps its base64 if its type is BINARY; otherwise the parameter is removed and the value decoded.
• Structure: the root element is icalendar (the stream), holding one or more vcalendar elements, each with a properties element and a components element. Component elements (vevent, vtodo, vjournal, vfreebusy, vtimezone, standard, daylight, valarm) go inside components, which can nest. Every element name is the lower-case iCalendar name.
• Property: an element with the property's lower-case name; at most one parameters element (left out when empty), whose children are the parameters, lower-case, each containing a value element; then one or more value elements. A VALUE parameter is not written, because the value element's name says the type; when converting back it is added if the type is not the property's default.
• Value elements (lower-case type names): binary, boolean, cal-address, date, date-time, duration, float, integer, period (children start and end or duration), recur, text, time, uri, utc-offset. Dates and times follow XML Schema syntax with - and : separators (2011-05-17T12:00:00) and, as in iCalendar, no UTC offset (zones are by TZID parameter); utc-offset is written -05:00. A recur element has a child per rule part (freq, count, byday, bymonth...).
• Multi-valued properties (CATEGORIES, RESOURCES, FREEBUSY, EXDATE, RDATE) hold several value elements. GEO holds latitude and longitude elements; REQUEST-STATUS holds code, description and, if there is any, data.
• Extensions and unknowns: an X-FOO property is the element x-foo in the iCalendar namespace (and elements there must begin x-). A property whose default type is unknown and that has no VALUE parameter, and any unrecognised parameter, gets the value element unknown holding the raw text; converting back writes it unchanged with no VALUE parameter. Elements in another namespace that are direct children of properties are kept in the iCalendar form as the XML property.
• XML property: text (or BINARY base64 with ENCODING=BASE64;VALUE=BINARY when the XML has characters TEXT cannot hold) containing one XML 1.0 element with a namespace declaration, not in the iCalendar namespace and not duplicating a defined property; any number of times in any component; order is not preserved.

iCalendar in JSON: jCal (RFC 7265)

Media type application/calendar+json (optional parameters method, component, optinfo).

• Pre-processing: unfold, then remove iCalendar escaping (RFC 5545 and RFC 6868), then apply JSON escaping; the reverse order on the way back, and fold long lines. Base64 is handled as in xCal. JSON numbers cannot have leading zeros or a plus sign.
• Stream: no equivalent; several objects are a JSON array.
• Component: a fixed three-element array: lower-case name, array of properties, array of sub-components. Property order within a component is not kept.
• Property: an array: lower-case name, an object of parameters (empty {} if none), the lower-case value type, then one value (single-valued properties have exactly four elements) or several (multi-valued ones). Example: ["categories", {}, "text", "Meetings", "Work"].
• Parameters: object keys are lower-case parameter names; the value keeps its case. Multi-valued parameters (delegated-to, delegated-from and others) are arrays of strings (a parser must accept a plain string for a single value). The quotes around a value with a colon, semicolon or comma are not part of the value. The VALUE parameter is not written; the type string takes its place: the VALUE parameter if present, else the property's default type, else unknown. Converting back omits VALUE for unknown and for default types and adds it otherwise.
• Values: binary base64 string; boolean JSON boolean; cal-address and uri strings; date YYYY-MM-DD; date-time YYYY-MM-DDTHH:MM:SS with an optional zone (Z); time HH:MM:SS; reduced-accuracy forms are not allowed; duration as in RFC 5545; float and integer JSON numbers (an integer must fit the RFC 5545 range); period a two-element array of start and end (date-time) or duration; text a string; utc-offset with a colon (-05:00); recur an object with lower-case keys, where freq and wkst are strings with case kept, until is a date or date-time, count and interval numbers, bysecond, byminute, byhour, bymonthday, byyearday, byweekno, bymonth, bysetpos numbers or arrays of numbers, and byday a string or array of strings ({"freq": "YEARLY", "count": 5, "byday": ["-1SU", "2MO"], "bymonth": 10}).
• Special properties: geo is a two-element array [latitude, longitude] of floats; request-status is an array of two or three strings (code, description, and data unless empty); converting back joins them with semicolons.
• Extensions and unknowns: X-FOO becomes x-foo. A new value type, unknown, holds the raw text of a property whose default type is not known; it is reserved in iCalendar (IANA status "Reserved - Do not use") so it never occurs in a real iCalendar file.