Proposal: scheduleTimezone

[nickevansuk]

Proposer

ODI

Use Case

The startTime and endTime of the schedule are currently underspecified, but in practice we recommend they are rendered into the feed in the local time of the associated location (rather than UTC).

This requires the data user to look up the timezone based on the geo lat/lng of the location (which is optional, and the Event may only include a free-text address field at a minimum), in order to resolve the time. As an aside: resolving time from location is not always possible depending on the geography (e.g. the West Bank has two timezones in the same location), so this is inherently flawed.

Further related issues:

• https://github.com/openactive/realtime-paged-data-exchange/issues/91
• https://github.com/openactive/data-model-validator/issues/278
• https://github.com/schemaorg/schemaorg/issues/1457#issuecomment-399227151

As explained here timezones are difficult to calculate, so we should steer away from anything that requires embedding of the specific rules of a timezone. iCal does this using TZID.

Proposal

The Schedule should include a new required property named timeZone, to mirror the iCal TZID (and this should be recommended for inclusion in the schema.org pending implementation too).

The property should be constrained to the values of TZ from the time zone database (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).

This also means that it will be natively supported by libraries such as moment.js.

Additionally from this discussion we should mandate that DateTime properties such as startDate and endDate MUST include timezone designator and SHOULD default to the local timezone of the Event (as per unresolved item in https://github.com/openactive/modelling-opportunity-data/issues/78).

Validator rules

• timeZone is required within Schedule
• timeZone is required within PartialSchedule if either startTime or endTime are set

Example

        "eventSchedule": [
          {
            "type": "PartialSchedule",
            "repeatFrequency": "P1W",
            "startTime": "20:15",
            "endTime": "20:45",
            "timeZone": "Europe/London",
            "byDay": [
              "http://schema.org/Tuesday"
            ]
          }
        ],

Beta property

(Class) Property	Expected Type	Description
(pending:Schedule) beta:timeZone	schema:Text	The time zone used to generate occurrences, same as iCal TZID. E.g. 'Europe/London'.

[nickevansuk]

An simpler alternative is that we always assume that the startTime and endTimeare in "floating time" (https://tools.ietf.org/html/rfc5545#section-3.3.5), and that they should just be rendered as-is to the user (6pm is always considered 6pm regardless of the user's timezone).

However, this makes it difficult to generate subEvents from a schedule, as startDate and endDate properties in the subEvents require a timezone (mentioned in https://github.com/openactive/modelling-opportunity-data/issues/78, but not yet included in the spec).

If the schedule is specified in floating time, the subEvents will also need to be generated in floating time (assuming no location-based time zone inference is applied).

Which then leads us to question using timezones at all - should all dates always just be specified in floating time based on the local time of the provider? This would remove the complexity of timezones, but this would create limitations around compatibility with Google Calendar and other systems that use incremental time.

It is not possible to accurately translate between floating and incremental time without making assumptions about location etc, though it looks like Google accepts both: https://developers.google.com/search/docs/data-types/event

Further reading:

• https://www.w3.org/TR/timezone/#observedtime
• https://www.w3.org/International/articles/definitions-time/#incremental_time
• https://www.w3.org/International/articles/definitions-time/#floating_time

[nickevansuk]

Following a reference implementation of this, I have observed the following:

• Given UTC is in use amongst all publishers due to the RPDE recommendations, we should avoid switching to "floating time" as this would effectively constitute a breaking change at this stage.
• The timeZone / iCal tzid field is essential to deriving the occurrences in incremental time, and the rrule library (as well as its Ruby and Python counterparts) include native support for it. If not supplied, an assumption would need to be made by the data user based on the event location.
• The rrule library also includes an option for the endDate to be inclusive or exclusive. We should define this behaviour in the spec, so that the generation is well defined. Suggest we use the iCal default, or otherwise inclusive if iCal doesn't have a default.
• The rrule library allows for a set of rrules to be constructed, which maps to an array of Schedule as we've defined in the spec.
• In order to make the data more useful, I recommend that the "always specify date/times in UTC" recommendation be revised to "always specify date/times with the timezone designator set to the local timezone of the Event".

[nickevansuk]

Proposed way forward

Add timeZone as per original proposal, as floating time is much less useful and requires more radical changes across all existing implementers

[nickevansuk]

Noting this has now been added to schema.org as schema:scheduleTimezone, however this still needs to be added as a REQUIRED property to Schedule and PartialSchedule in the modelling specification.

[nickevansuk]

Note an outstanding specification change based on the above, which is required for booking:

In order to make the data more useful, I recommend that the "always specify date/times in UTC" recommendation be revised to "always specify date/times with the timezone designator set to the local timezone of the Event".

See also https://github.com/openactive/realtime-paged-data-exchange/issues/88