The iCalendar Format, Explained

After reading this you will know how an .ics file stores a calendar event byte by byte, why the same event can show up at 9:00 in one place and 2:00 in another, and how to write files that strict parsers accept.

What an .ics file actually is

An iCalendar file is plain text. Open one in a text editor and you see readable lines, each with a property name, a colon, and a value. The format is defined by RFC 5545. A single event looks like this:

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//ABC Tools//iCal Generator//EN
BEGIN:VEVENT
UID:1a2b3c@abctools
DTSTAMP:20240115T090000Z
DTSTART:20240620T100000
DTEND:20240620T110000
SUMMARY:Team standup
END:VEVENT
END:VCALENDAR

The whole thing is wrapped in a VCALENDAR container. Inside it sits one VEVENT block. Google Calendar, Outlook and Apple Calendar all read this same structure, which is why one file imports everywhere.

The character set is UTF-8, and line endings are CRLF (carriage return plus line feed, bytes 0D 0A). That CRLF requirement is real: some strict parsers reject files that use bare 0A line feeds.

When to use it, and when not to

Reach for an .ics file when you want to hand someone an event they can add to their own calendar in one click. Conference schedules, appointment confirmations, and "add to calendar" buttons on a web page all use this. The file is self-contained, so it works offline and needs no account.

Do not use .ics as a general database. It has no query language, no indexes, and it is verbose: a single event with a description of 200 characters can produce a 500-byte file once you add the required headers. For storing contacts rather than events, use the vCard Generator & Parser instead, which speaks the .vcf format built for that job.

How dates and times are encoded

Every timestamp uses the same compact layout: four-digit year, two-digit month, two-digit day, the letter T, then hours, minutes and seconds. So 20240620T100000 means 20 June 2024 at 10:00:00. There are exactly three forms, and the difference decides where the event lands.

Floating local time

Written with no suffix: DTSTART:20240620T100000. It means "10:00 wherever the viewer is." A meeting at this time shows at 10:00 in London and 10:00 in Tokyo. Good for a wake-up alarm, bad for a global call.

UTC time

Written with a trailing Z: DTSTART:20240620T100000Z. The Z stands for Zulu, meaning UTC. This is an absolute instant. It shifts on the viewer's clock: 10:00 UTC shows as 11:00 in London during summer and 19:00 in Tokyo.

Zoned time

Written with a TZID parameter, like DTSTART;TZID=Europe/London:20240620T100000, and paired with a VTIMEZONE block that spells out the offset rules. This is the most precise but the most verbose.

The offset from UTC to a viewer's wall clock is a simple addition:

Here t_{\text{UTC}} is the instant stored in the file, \Delta_{\text{tz}} is the viewer's offset from UTC (for example +9 hours in Tokyo), and t_{\text{local}} is what appears on screen. For a floating time, no offset is applied at all, so the displayed hour never changes.

Line folding and escaping

RFC 5545 limits a line to 75 octets. Longer values must be folded: split the value and begin the continuation line with a single space or tab. A parser rejoins folded lines by deleting the CRLF and the one leading whitespace character. So a 120-character description becomes two physical lines but one logical value.

Certain characters inside a value carry meaning and must be escaped with a backslash:

A description of "Bring laptop, charger; notes attached" must be stored as Bring laptop\, charger\; notes attached. Skip the escaping and a strict parser either truncates the value at the comma or throws an error.

A worked example you can reproduce

Reading an existing file

When you paste an .ics file into the parser, it unfolds the lines, un-escapes the text values, and lists each VEVENT with its resolved fields. The parser also tells you which time form each event uses, so you can predict how it will display.

Count the events per day in a large export and you get a quick sense of a schedule's shape. The chart below shows a week where meetings cluster mid-week.

If a parser shows an event an hour off from what you expect, check the suffix. A missing Z on what should be a UTC time is the usual cause, and it moves the event by exactly the viewer's offset.

Common mistakes

Other pitfalls appear often enough to name:

• Using LF line endings instead of CRLF. The file may open fine in one app and fail to import in another.
• Reusing a UID across events, which makes a calendar treat the second as an edit of the first.
• Forgetting to escape a comma or semicolon inside SUMMARY or DESCRIPTION, which truncates the text.
• Writing an all-day event with a time. All-day events use DTSTART;VALUE=DATE:20240620 with a date and no T.

Related tools

To fill fields with realistic placeholder titles and locations while testing an import pipeline, generate them with the Test Data Generator. To turn a per-weekday event count like the one above into a shareable image, paste the numbers into the Chart Maker.

Related tools

JSON → Types Generator

Generate TypeScript, Python or Go types from JSON.

Test Data Generator

Fake names, emails, addresses — CSV or JSON datasets.

XML Formatter & Validator

Pretty-print, minify and validate XML.

vCard Generator & Parser

Create .vcf contact files and inspect existing ones.

Auto Analyst: Instant Statistical Report

Drop a CSV or Excel file and get a statistician’s report: data problems, distributions, every real relationship, key drivers and Simpson’s paradox warnings, in plain English.

CSV Viewer & Editor

View, edit, sort, filter and extract columns from CSV files.