What's VTIMEZONE used for in icalendar? Why not just UTC time?

Question

What's VTIMEZONE used for in icalendar?

e.g. 1

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Apple Inc.//Mac OS X 10.12.3//EN
CALSCALE:GREGORIAN
BEGIN:VTIMEZONE
TZID:Asia/Shanghai
BEGIN:STANDARD
TZOFFSETFROM:+0900
RRULE:FREQ=YEARLY;UNTIL=19910914T150000Z;BYMONTH=9;BYDAY=3SU
DTSTART:19890917T000000
TZNAME:GMT+8
TZOFFSETTO:+0800
END:STANDARD
BEGIN:DAYLIGHT
TZOFFSETFROM:+0800
DTSTART:19910414T000000
TZNAME:GMT+8
TZOFFSETTO:+0900
RDATE:19910414T000000
END:DAYLIGHT
END:VTIMEZONE
BEGIN:VEVENT
TRANSP:OPAQUE
LAST-MODIFIED:20170305T083916Z
UID:gjo1burcjnsib4p2j8tbbv4hh0@google.com
DTSTAMP:20170305T083916Z
LOCATION:Cell Group
DESCRIPTION:
STATUS:CONFIRMED
SEQUENCE:0
SUMMARY:Study Bible
DTSTART;TZID=Asia/Shanghai:20170324T193000
DTEND;TZID=Asia/Shanghai:20170324T213000
X-APPLE-TRAVEL-ADVISORY-BEHAVIOR:AUTOMATIC
CREATED:20160312T140632Z
RRULE:FREQ=WEEKLY;BYDAY=FR
BEGIN:VALARM
X-WR-ALARMUID:9B47E27E-9063-417E-B488-409387A3201A
UID:9B47E27E-9063-417E-B488-409387A3201A
TRIGGER;VALUE=DATE-TIME:19760401T005545Z
ACKNOWLEDGED:20161125T105826Z
X-APPLE-DEFAULT-ALARM:TRUE
ACTION:NONE
END:VALARM
END:VEVENT
END:VCALENDAR

From iCalendar Documentation

VTIMEZONE: provides a grouping of component properties that defines a time zone.

1. What's the definition of VTIMEZONE?

Is a rule to describe winter time and summer time for a location?

2. What's VTIMEZONE used for?

I don't have to specify a VTIMEZONE component in icalendar object. Instead, I transofrm my local time to utc time, and export icalendar event.

# Before
DTSTART:20170324T113000Z
DTEND:20170324T130000

# After
DTSTART;TZID=Asia/Shanghai:20170324T193000
DTEND;TZID=Asia/Shanghai:20170324T213000

2.1 Does this make sense? a icalendar object without VTIMEZONE

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Apple Inc.//Mac OS X 10.12.3//EN
BEGIN:VEVENT
TRANSP:OPAQUE
LAST-MODIFIED:20170305T083916Z
UID:gjo1burcjnsib4p2j8tbbv4hh0@google.com
DTSTAMP:20170305T083916Z
LOCATION:Cell Group
DESCRIPTION:
STATUS:CONFIRMED
SEQUENCE:0
SUMMARY:Study Bible
DTSTART;TZID=Asia/Shanghai:20170324T113000
DTEND;TZID=Asia/Shanghai:20170324T213000
X-APPLE-TRAVEL-ADVISORY-BEHAVIOR:AUTOMATIC
CREATED:20160312T140632Z
RRULE:FREQ=WEEKLY;BYDAY=FR
BEGIN:VALARM
X-WR-ALARMUID:9B47E27E-9063-417E-B488-409387A3201A
UID:9B47E27E-9063-417E-B488-409387A3201A
TRIGGER;VALUE=DATE-TIME:19760401T005545Z
ACKNOWLEDGED:20161125T105826Z
X-APPLE-DEFAULT-ALARM:TRUE
ACTION:NONE
END:VALARM
END:VEVENT
END:VCALENDAR

2.2 If this makes sense, what's the usage of VTIMEZONE?

3. Consistence between VTIMEZONE and VEVENT

Take e.g. 1 for example.

....
BEGIN:VTIMEZONE
TZID:Asia/Shanghai                           <- Part 1
.....
END:VTIMEZONE


BEGIN:VEVENT
....
DTSTART;TZID=Asia/Shanghai:20170324T193000   <- Part 2
DTEND;TZID=Asia/Shanghai:20170324T213000     <- Part 3
....
END:VEVENT

3.1. Must timezone in VEVENT be consistent with VTIMEZONE?

3.2 Can I use other timezone to describe time in part2 and part3?

e.g.

....
BEGIN:VTIMEZONE
TZID:Asia/Shanghai                           <- Part 1
.....
END:VTIMEZONE


BEGIN:VEVENT
....
DTSTART:20170324T193000Z   <- Part 2 UTC time
DTEND:20170324T213000Z     <- Part 3 UTC Time
....
END:VEVENT

Answer 1

1. What's the definition of VTIMEZONE?

VTIMEZONE is used to store the specific rules for the UTC offset a timezone has at any given point in time (i.e. when it is daylight savings time and when it is standard time).

2. What's VTIMEZONE used for?

It's used when you want to format your various timestamps throughout the iCalendar under a specific timezone instead of UTC.

You might ask: Why not just use UTC everywhere? Wouldn't it be simpler? The answer is: timezones are needed because of recurrence rules. If you have a repeating event, and that event crosses a daylight/standard boundary, you have to specify a timezone for that event. If you just used UTC, the event's time would become incorrect once you passed the daylight/standard boundary.

2.1 Does this make sense? a icalendar object without VTIMEZONE

Your example is incorrect.

The DTEND property in your example is referencing a VTIMEZONE component that does not exist ("Asia/Shanghai").

DTEND;TZID=Asia/Shanghai:20170324T213000

An iCalendar parser will look at that TZID parameter, and then look for a VTIMEZONE component whose TZID property matches it. Because your iCalendar object does not have such a VTIMEZONE, the iCalendar parser technically doesn't know how to interpret that date. The TZID parameter is merely treated as a unique identifier. It does not have any meaning in and of itself.

If you want a date to be formatted under a specific timezone, but you do not want to include a VTIMEZONE component in your iCalendar object, you can use a global timezone ID. Global timezone IDs are different from normal TZID parameters because they begin with a forward slash:

DTEND;TZID=/Asia/Shanghai:20170324T213000

The downside to global timezone IDs is that the iCalendar specification does NOT specify how these IDs are supposed to be interpreted by the parser. However, in practice, I would imagine that out of all the parsers that support global IDs, most of them probably treat them as Olson IDs.

3.1. Must timezone in VEVENT be consistent with VTIMEZONE?

The timezone(s) defined in the VTIMEZONE component(s) have global scope across the iCalendar object. So any TZID parameter in a VEVENT must reference a VTIMEZONE component (unless it is a global timezone ID).

3.2 Can I use other timezone to describe time in part2 and part3?

Just because your iCalendar object has a VTIMEZONE component, doesn't mean you have to use it. Your example is valid.

Answer 2

From a programmer under time pressure... VTIMEZONE is difficult to manage in icalendar.py

I took the following shortcut:

from datetime import datetime
import pytz
import icalendar

mytz = pytz.timezone('<your timezone>')
timestamp = datetime.now().replace(second=0, microsecond=0)

# ... < Lots of code there >
event.add('dtstamp',vDatetime(mytz.localize(timestamp).astimezone(pytz.UTC)))
3 --- < tons of code here >

And did the same for dtstartand dtend