This is a card in Dave's Virtual Box of Cards.

iCalendar (ical/ics) VTIMEZONE definitions

Page created: 2023-06-17

I’ve got this icalendar-viewer tool where people can paste the .ics invite excrement attached to invite emails generated by trashy tools written by, for example, Microsoft.

Here’s the link to the relevant RFC 5545 (rfc-editor.org).

To figure out when an invite is supposed to happen, particularly for a recurring event where additional local calculation will need to be done, an invite may provide a "VTIMEZONE" to define rules for calculating offsets from UTC.

Here’s a (modified) simple example from the RFC:

       BEGIN:VTIMEZONE
       TZID:America/New_York

       BEGIN:DAYLIGHT
       DTSTART:20070311T020000
       TZOFFSETFROM:-0500
       TZOFFSETTO:-0400
       TZNAME:EDT
       END:DAYLIGHT

       BEGIN:STANDARD
       DTSTART:20071104T020000
       TZOFFSETFROM:-0400
       TZOFFSETTO:-0500
       TZNAME:EST
       END:STANDARD

       END:VTIMEZONE

Note that this example only specifies the UTC offsets for two time periods:

After 2007-03-11 02:00 (DTSTART for "daylight" time) we have an offset from UTC of -4 hours.
After 2007-11-04 02:00 (DTSTART for "standard" time) we have an offset from UTC of -5 hours.

In other words, we have no idea what the offset is prior to 2007-03-11 and we have to assume any date after 2007-11-04 is still in the "daylight" time offset!

An event may specify a date-time with this timezone by using the TZID "America/New_York":

BEGIN:VEVENT
DTSTART;TZID=America/New_York:20070616T100000
...
END:VEVENT

Which, in this case, would mean the event is for 2007-06-16 10:00 New York "Standard" time (aka EST) because it’s after 2007-03-11 and before 2007-11-04.

So, in perhaps more recognizable terms, that’s 10:00 EST.

Again, that’s 10:00 at UTC -0400 (or 14:00 UTC) according to this VTIMEZONE definition.

Events without without a TZID

Note that you can also specify an event without a TZ:

BEGIN:VEVENT
DTSTART:20070616T100000
...
END:VEVENT

Which means the time is specified for 10:00 "local time" no matter what local time happens to be! I presume this is rare!

Or in UTC with an explicit "Z" at the end:

BEGIN:VEVENT
DTSTART:20070616T100000
...
END:VEVENT

Timezone recurrence rules

A VTIMEZONE with different "standard" and "daylight" components should probably have a RRULE (recurrence rule) in order to make complete sense:

       BEGIN:VTIMEZONE
       TZID:America/New_York
       BEGIN:DAYLIGHT
       DTSTART:19670430T020000
       RRULE:FREQ=YEARLY;BYMONTH=4
       ...
----

This one says that the "daylight" time offset starts every year on
month 4. There's other garbage you can put in there.