iCalendar Overview

iCalendar is an open file format for transmitting scheduling information, such as meeting times and event announcements, across a network. It is supported by a large number of popular applications, including Google Calendar, Apple Calendar, and Microsoft Outlook. iCalendar files end with a .ics extension. The latest iCalendar specification is defined in RFC 5545.

The iCalendar data model consists of components and properties. A component consists of a collection of properties and components (components can be nested within other components). A property consists of a name, a list of parameters (key/value attributes), and a value.

Lines that start with "BEGIN:" mark the beginning of a component, and lines that start with "END:" mark the end of a component. All data in an iCalendar object is contained within a top-level "VCALENDAR" component.

Each line of text within a component is a property. The property's name is located at the beginning of the line. The property's parameters are located in between the property name and the first colon character. The property's value is located after the first colon character.

Properties with large values are typically folded, meaning their values are split across multiple lines. Folded lines are identified by the fact that they begin with a whitespace character (a space or a tab). Most iCalendar producers fold lines when they get to be between 70-80 characters long (the iCal specification recommends 75 characters).

The iCalendar object below contains the date and time for a biweekly, one hour long team meeting. The DESCRIPTION property has a large value, and is folded across three lines. The comma character in this property value is escaped with a backslash because commas have a special meaning in some property values. It was generated by Microsoft Outlook and adheres to the latest version of the iCalendar standard (2.0).

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Microsoft Corporation//Outlook 14.0 MIMEDIR//EN
BEGIN:VEVENT
UID:d6d88f2e50080b9602da53dac1102762
DTSTAMP:20130601T080000Z
SUMMARY;LANGUAGE=en-us:Team Meeting
DESCRIPTION:Lorem ipsum dolor sit amet\, consectetur adipiscing elit. Vesti
 bulum ultricies tempor orci ac dignissim. Curabitur posuere consequat mass
 a.
DTSTART:20130610T120000Z
DURATION:PT1H
RRULE:FREQ=WEEKLY;INTERVAL=2
END:VEVENT
END:VCALENDAR

Multiple iCalendars can exist inside of the same data stream. The text below contains two iCalendars.

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Microsoft Corporation//Outlook 14.0 MIMEDIR//EN
BEGIN:VEVENT
UID:d6d88f2e50080b9602da53dac1102762
DTSTAMP:20130601T080000Z
SUMMARY;LANGUAGE=en-us:Team Meeting
DTSTART:20130610T120000Z
DURATION:PT1H
RRULE:FREQ=WEEKLY;INTERVAL=2
END:VEVENT
END:VCALENDAR
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Microsoft Corporation//Outlook 14.0 MIMEDIR//EN
BEGIN:VEVENT
UID:cb541cd5bf9c4abfae00c31cdb02b264
DTSTAMP:20130701T080000Z
SUMMARY;LANGUAGE=en-us:Keynote Speech
DTSTART:20130715T130000Z
DTEND:20130715T140000Z
END:VEVENT
END:VCALENDAR

iCalendar data can also be encoded in XML ("xCal") and JSON ("jCal") formats.

XML

<?xml version="1.0" encoding="utf-8"?>
<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
  <vcalendar>
    <properties>
      <version>
        <text>2.0</text>
      </version>
      <prodid>
        <text>-//Microsoft Corporation//Outlook 14.0 MIMEDIR//EN</text>
      </prodid>
    </properties>
    <components>
      <vevent>
        <properties>
          <uid>
            <text>d6d88f2e50080b9602da53dac1102762</text>
          </uid>
          <dtstamp>
            <date-time>2013-06-01T08:00:00Z</date-time>
          </dtstamp>
          <summary>
            <parameters>
              <language>
                <text>en-us</text>
              </language>
            </parameters>
            <text>Team Meeting</text>
          </summary>
          <dtstart>
            <date-time>2013-06-10T12:00:00Z</date-time>
          </dtstart>
          <duration>
            <duration>PT1H</duration>
          </duration>
          <rrule>
            <recur>
              <freq>WEEKLY</freq>
              <interval>2</interval>
            </recur>
          </rrule>
        </properties>
      </vevent>
    </components>
  </vcalendar>
</icalendar>

JSON

["vcalendar",
  [
    ["version", {}, "text", "2.0"],
    ["prodid", {}, "text", "-//Microsoft Corporation//Outlook 14.0 MIMEDIR//EN"]
  ],
  [
    ["vevent",
      [
        ["uid", {}, "text", "d6d88f2e50080b9602da53dac1102762"],
        ["dtstamp", {}, "date-time", "2013-06-01T08:00:00Z"],
        ["summary", {"language":"en-us"}, "text", "Team Meeting"],
        ["dtstart", {}, "date-time", "2013-06-10T12:00:00Z"],
        ["duration", {}, "duration","PT1H"],
        ["rrule", {}, "recur", {"freq":"WEEKLY", "interval":2}]
      ],
      []
    ]
  ]
]