Info from Mozilla on iCalendar spec

[ptomato]

@dminor mentioned that there was some feedback from Thunderbird on the recent normative change to limit the precision of offset time zones, regarding the iCalendar spec. This issue is a reminder that we need to get in touch to hear the feedback.

[dminor]

Thanks for opening the issue :)

cc @leftmostcat

[justingrant]

As part of working on #2607, I researched whether iCalendar (RFC 5545) and it's JSON equivalent JSCalendar (RFC 8984) would be affected by #2607's change to limit offset time zones to minutes precision.

My conclusion was that it would NOT impact these RFCs, because those RFCs only use UTC offset strings as part of definitions of custom time zones. What we changed in #2607 was only the allowed syntax for offset time zone identifier strings like +05:30. IANA Time Zones and custom-object time zones are still allowed at nanosecond precision, which is AFAICT the only way that iCalendar and JSCalendar use offsets.

That said, I'm not an iCalendar nor JSCalendar expert so would definitely appreciate a second opinion. It might be that iCalendar implementations like Thunderbird have expectations around the translation of TZID names inside VTIMEZONE sections (see below for what those terms mean) that aren't spelled out in the spec but are used in the wild. So it would be good to hear more from those folks.

Here's a summary of what I know:

iCalendar (RFC 5545)

iCalendar deals with time zones in two places: DATE-TIME that is used to specify the start date/time of an event, and VTIMEZONE that defines time zone rules.

A DATE-TIME property is like a Temporal instance. Its value can be iCalendar equivalent (equivalent meaning the same data model) of a Temporal.PlainDateTime, a Temporal.Instant, or a Temporal.ZonedDateTime.

DATE-TIME can have three possible forms:

• FORM #1: DATE WITH LOCAL TIME - analogous to Temporal.PlainDateTime, e.g. 19980118T230000
• FORM #2: DATE WITH UTC TIME - Analogous to Temporal.Instant, e.g. 19980119T070000Z1
• FORM #3: DATE WITH LOCAL TIME AND TIME ZONE REFERENCE - Analogous to Temporal.ZonedDateTime, albeit with different syntax, e.g. TZID=America/New_York:19980119T020000

Of these, only Form #3 is capable of including a time zone identifier, but these identifiers are not built-in IDs that the system knows how to interpret. Instead, the TZID value inside a DATE-TIME property is a reference to the TZID property inside a VTIMEZONE section defined in an iCalendar message. It's a pointer. Per the spec:

  An
  individual "VTIMEZONE" calendar component MUST be specified for
  each unique "TZID" parameter value specified in the iCalendar
  object.

A VTIMEZONE section is like one of the time zone definitions inside the IANA Time Zone Database. It defines the offsets and transitions that correspond to a particular named time zone. Here's an example:

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

The only part of iCalendar grammar that includes UTC offsets is the UTC-OFFSET property, which is only used as part of the time zone rules definition inside a VTIMEZONE section. The TZOFFSETFROM and TZOFFSETTO properties can contain optional seconds, e.g. TZOFFSETFROM:+080001

In other words, just like the IANA Time Zone Database can (and does!) define named time zones that have offsets with sub-minute precision, a VTIMEZONE section can also define a time zone with seconds precision.

Pulling all this info together, my understanding is that a VTIMEZONE section is equivalent to a custom time zone object in ECMAScript. If an iCalendar VTIMEZONE section includes a seconds-granularity offset, then this can be modeled in ECMAScript by building a custom time zone object whose getOffsetNanosecondsFor method returns values with seconds granularity.

JSCalendar (RFC 9884)

JSCalendar is, to the best of my understanding, a port of iCalendar to idiomatic JSON with some additional features and improvements. Its data model is similar to iCalendar as described above, so I won't rehash the same info. But JSCalendar is a bit clearer when it comes to time zones, so I'll document a few things I saw:

Time zone IDs are more clearly defined than in iCalendar. See https://datatracker.ietf.org/doc/html/rfc8984#section-1.4.8:

Where TimeZoneId is given as a data type, it means a String that is either a time zone name in the IANA Time Zone Database [TZDB] or a custom time zone identifier defined in the timeZones property (see Section 4.7.2).

A custom time zone ID has the following constraint (per https://datatracker.ietf.org/doc/html/rfc8984#section-4.7.2-3.1):

To avoid conflict with names in the IANA Time Zone Database [TZDB], it MUST start with the / character.

So JSCalendar is even more restrictive than iCalendar: a JSCalendar time zone ID can never be an offset time zone ID like +05:30 or -02.

Also, per https://datatracker.ietf.org/doc/html/rfc8984#section-4.7.2-6:

A TimeZone object maps a VTIMEZONE component from iCalendar, and the semantics are as defined in [RFC5545].

[leftmostcat]

Justin, thank you for the detailed write-up and the clarification. Given that this is restricted to offset time zones identifiers, the following ends up being moot and there should be no issue with representation of data in RFC 5545.

Having said that, I was able to speak with members of CalConnect's TC-CALENDAR (which is the committee overseeing RFC 5545 and its extensions as well as RFC 9884) today; they indicated that they're not aware of any instances of iCalendar being used to represent sub-minute precision in time zones and noted that such data is unlikely to occur for dates following the epoch.

From the perspective of Thunderbird itself, we handle time zones generally in one of two ways: when a VTIMEZONE identifier matches an IANA tzdb identifier, we simply use the IANA definition represented in a VTIMEZONE-adjacent structure. If the identifier does not match, we make direct use of the VTIMEZONE data. Given what I understand of the capabilities of time zones in Temporal, this shouldn't be an issue for us either. And on top of all of that, Thunderbird itself doesn't expose seconds to the user at present and I'm unaware of any bug reports concerning this.

All in all, it looks like there's no problem for iCalendar.

[justingrant]

Meeting 2023-08-17: Based on discussion above, there's no conflict with iCalendar, which supports sub-minute offsets only when defining what in Temporal would be a custom time zone. Temporal also supports sub-minute-offsets in that case, as well as in Temporal.Instant strings. The only case where sub-minute offsets are not allowed is in offset time zones, which AFAICT do not exist in iCalendar at all.

Closing.