.VCS File Format – Syntax, grammar and transport

What a vCalendar is

A format for exchanging the event (a scheduled amount of time on a calendar) and to-do (an action item or assignment) entities of calendar and scheduling programs, independent of how it is transported: a file, a point-to-point link, a network or a wireless link. A vCalendar is a data stream of one or more vCalendar objects, each identifiable and parseable within the stream. Conceptually a writer creates streams and a reader interprets them; the specification defines only the format. It is a clear-text encoding made to work where only 7-bit transfer, short lines and low bandwidth are available, and simple enough for small devices such as personal digital assistants, mobile phones and pagers. Date and time values follow ISO 8601. Unlike a CSV or tab-delimited export it keeps the meaning of the original objects. Its model came from the X.400 API Association's Calendaring and Scheduling API.

Object model

• vCalendar object: begins with BEGIN:VCALENDAR as the first characters of the stream or of a line, ends with END:VCALENDAR as the first characters of a line, and contains the calendar properties then any number of event and to-do entities. A stream can hold several objects.
• vEvent: between BEGIN:VEVENT and END:VEVENT, each at the start of a line. vTodo: BEGIN:VTODO and END:VTODO. Neither may be nested inside the other or inside itself; relations between them are expressed with the RELATED-TO property.
• Order: the calendar properties (VERSION is required, then PRODID, TZ, DAYLIGHT, GEO) come after BEGIN:VCALENDAR and before the first entity, and apply to the whole object unless overridden inside an entity.

Line syntax

• Property: one or more lines of the form PropertyName [";" PropertyParameters] ":" PropertyValue, for example DTSTART:19960415T083000. The name is one of the defined strings (or an extension), must be the first characters of a line, and names and parameters are case-insensitive. Values are strings.
• Parameters follow the name after a semicolon, written name=value or, where the value is unambiguous, as the value alone. The full form DESCRIPTION;ENCODING=QUOTED-PRINTABLE:... has the short form DESCRIPTION;QUOTED-PRINTABLE:.... A semicolon inside a parameter value is escaped with a backslash. The grammar names these parameters: TYPE, VALUE, ENCODING, CHARSET, LANGUAGE, ROLE, STATUS and X- names.
• Lines end with CR LF (RFC 822). A long line can be folded by inserting CR LF followed by at least one white space character wherever linear white space may occur; unfolding treats CR LF plus a white space character as that white space character. Folding should be done at higher-level breaks of structured values.
• Line breaks inside a value are also CR LF, which would end the line, so such values must use quoted-printable or base64: in quoted-printable a line break is =0D=0A and a soft line break is a trailing =, with lines under 76 characters. Example: DESCRIPTION;ENCODING=QUOTED-PRINTABLE:Project XYZ Final Review=0D=0A= then a continuation line of leading white space, Conference Room - 3B=0D=0A=, Come Prepared.
• Compound values have components separated by a semicolon; a semicolon inside a component is escaped with a backslash.

Encodings, character set, language, times and locations

• Encoding. The default for the object is 7-bit; the ENCODING parameter (any property) can say BASE64, QUOTED-PRINTABLE or 8-bit for one value. A transport such as MIME mail may carry its own encoding at the wrapper level for a stream whose default is 8-bit.
• Character set. The default is ASCII; CHARSET (any property, though it makes no sense on some) names an IANA-registered set, for example DESCRIPTION;CHARSET=ISO-8859-8:.... A transport wrapper may carry a default charset such as UTF-8.
• Language. The default is en-US; LANGUAGE takes an RFC 1766 tag, for example SUMMARY;LANGUAGE=fr-CA:.... It makes no sense on PHOTO, LOGO, SOUND or TEL.
• Date and time. ISO 8601 combined representation, basic or extended format; UTC should be used whenever possible. Basic complete form: <year><month><day>T<hour><minute><second><designator>, local 19960415T083000, UTC with Z 19960415T083000Z. A list of dates and times is separated by semicolons: 19960101T090000Z; 19960201T090000Z; ....
• Duration. ISO 8601 basic: P, optional years Y, months M, weeks W, days D, then optional T with hours H, minutes M, seconds S: P6W, PT15M, PT1H30M, P2Y10M15DT10H30M20S.
• Value location. By default a value is INLINE. VALUE=URL means the value is a URL of the resource; VALUE=CONTENT-ID (short CID) means it is the Content-ID of another MIME part of the message that carries the vCalendar. It makes no sense on VERSION, TZ, STATUS, PRIORITY, MALARM and the like. Example: ATTACH;VALUE=URL:http://www.abc.com/dir_photos/my_photo.gif.
• Binary values (images, audio, video): by URL, by Content-ID, or inline after base64 (the default) or quoted-printable encoding.
• Extensions. Property or parameter names starting X-, preferably followed by a vendor identifier (X-ABC-MMSUBJ;TYPE=WAV; VALUE=URL: http://load.noise.org/mysubj.wav). There is no registry of names. Readers must be able to parse extensions but may ignore them.

Formal grammar

The specification's BNF (RFC 822 style, names case-insensitive), abridged to the structure. Note that it writes the entity delimiters as "EVENT" and "TODO", while the prose and every example use VEVENT and VTODO; files use VEVENT and VTODO.

vcal_file   = [wsls] vcal [wsls]
vcal        = "BEGIN" [ws] ":" [ws] "VCALENDAR" [ws] 1*CRLF
              calprop calentities [ws] *CRLF
              "END" [ws] ":" [ws] "VCALENDAR" [ws] 1*CRLF
calentity   = evententity / todoentity       ; BEGIN/END "EVENT" and "TODO" as written
calprop     = "DAYLIGHT" / "GEO" / "PRODID" / "TZ" each [params] ":" value CRLF
            / "VERSION" [params] ":" "1.0" CRLF     ; VERSION MUST appear
entprop     = [ws] simprop [params] ":" value CRLF
            / "AALARM" [params] ":" aalarmparts CRLF      ; runTime;snoozeTime;repeatCount;audioContent
            / "DALARM" [params] ":" dalarmparts CRLF      ; ...;displayString
            / "MALARM" [params] ":" malarmparts CRLF      ; ...;addressString;noteString
            / "PALARM" [params] ":" palarmparts CRLF      ; ...;procedureName
            / "CATEGORIES" / "CLASS" / "EXDATE" / "RDATE" / "RESOURCES" / "STATUS"  with their value lists
simprop     = "ATTACH" / "ATTENDEE" / "DCREATED" / "COMPLETED" / "DESCRIPTION" / "DUE" / "DTEND" / EXRULE
            / LAST-MODIFIED / "LOCATION" / "RNUM" / "PRIORITY" / "RELATED-TO" / "RRULE" / "SEQUENCE"
            / "DTSTART" / "SUMMARY" / "TRANSP" / "URL" / "UID" / "X-" word
catvals     = "APPOINTMENT" / "BUSINESS" / "EDUCATION" / "HOLIDAY" / "MEETING" / "MISCELLANEOUS"
            / "PERSONAL" / "PHONE CALL" / "SICK DAY" / "SPECIAL OCCASION" / "TRAVEL" / "VACATION" / "X-" word / value
classvals   = "PUBLIC" / "PRIVATE" / "CONFIDENTIAL" / "X-" word / value
resvals     = "CATERING" / "CHAIRS" / "EASEL" / "PROJECTOR" / "VCR" / "VEHICLE" / "X-" word / value
statvals    = "ACCEPTED" / "NEEDS ACTION" / "SENT" / "TENTATIVE" / "CONFIRMED" / "DECLINED"
            / "COMPLETED" / "DELEGATED" / "X-" word / value
param       = "TYPE" "=" ptypeval / ["VALUE" "="] pvalueval / ["ENCODING" "="] pencodingval
            / "CHARSET" "=" charsetval / "LANGUAGE" "=" langval / "ROLE" "=" roleval
            / "STATUS" "=" statusval / "X-" word "=" word / knowntype
knowntype   = "WAVE" / "PCM" / "VCARD" / "X-" word / value
pvalueval   = "INLINE" / "URL" / "CONTENT-ID" / "CID" / "X-" word
pencodingval = "7BIT" / "8BIT" / "QUOTED-PRINTABLE" / "BASE64" / "X-" word
roleval     = "ATTENDEE" / "ORGANIZER" / "OWNER" / "X-" word
strnosemi   = *(*nonsemi ("\;" / "\" CRLF)) *nonsemi    ; semicolon escaped with a backslash
value       = 7bit / 8bit / quoted-printable / base64      ; in the encoding set for the value
word        = <any printable 7-bit US-ASCII except [ ] = : . ,>
base64      ; the text ends with two CRLF sequences, leaving a blank line before the next property

The damaged plain-text copy also has a rule groups = groups "." word / word, which the Word copy lacks and no property rule uses. The alarm values have 0 to 3 (audio, display, procedure) or 0 to 4 (mail) semicolon-separated parts after the run time, snooze time and repeat count, each part a string without unescaped semicolons.

Transport recommendations

Email (SMTP and MIME)

• As text in a message body. A vCalendar can simply be pasted into an RFC 822 message body after a human-readable introduction; this works with any mail system but gives none of MIME's benefits.
• As a text/plain part. A multipart/mixed message with a text part and a second part Content-Type: text/plain; charset=us-ascii; name="MARTIN.VCS" holding the vCalendar works with current MIME user agents.
• As text/x-vCalendar (a non-standard type, spelled text/x-vCalendar): Content-Type: text/x-vCalendar; charset=us-ascii; name="MARTIN.VCS"; this identifies the vCalendar clearly in the message. One object can hold both an event and a to-do.

Web (HTTP and HTML)

A server delivers a vCalendar with Content-Type: text/x-vCalendar (for example GET martin.vcs answers 200 OK with that content type and the object in the body). A page can embed it with the HTML 3.2 OBJECT element, <object data=martin.vcs type="text/x-vCalendar">, with fallback text linking to the file.

Desktop (file system, clipboard, drag and drop)

• File system. Support import and export through open and save-as; where the system has file types, use the type VCS.
• Clipboard. Support cut, copy and paste; where clipboard formats can be registered, register the ISO 9070 formal public identifier +//ISBN 1-887687-00-9::versit::PDI//vCalendar, and put the object on the clipboard both in that format and as plain text.
• Drag and drop. Act as drag source and drag target, registering the same identifier and offering the object both registered and as plain text. Where the system has several drag protocols (file based, clipboard based), support both: the file based one for dragging a desktop file or a web URL, the clipboard based one for dragging an event or to-do from one application to another.

Conformance

• All properties must be implemented as defined (statements elsewhere that call a feature optional, or make exceptions, take precedence).
• The default character set, US-ASCII, must be supported; others are optional.
• Extensions are optional; vendor extensions should carry a vendor identifier (X-ABC-) and must declare the minimum conformance for the extension. A reader must be able to parse a stream with extensions but need not act on them.