Schedules and PartialSchedules

Sometimes, a SessionSeries can include information about when it generally occurs (e.g. “it generally occurs on Mondays at 12:30pm and lasts 90 minutes”). These are Schedules or PartialSchedules and can be found in the eventSchedule array of a SessionSeries. Here’s what that would look like for the above example rule:

"eventSchedule": [
  {
    "type": "PartialSchedule",
    "byDay": [
      "schema:Monday"
    ],
    "duration": "PT1H30M",
    "startTime": "12:30",
    "endTime": "14:00",
    "startDate": "2020-06-22",
    "endDate": "2021-06-01",
    "repeatFrequency": "P7D",
    "scheduleTimezone": "Europe/London"
  }
],

This information can then be displayed on a website or mobile app to give the user a general idea of the session’s schedule. This might look like this:

Caution

The ScheduledSession has information about exactly when the session is going to take place.

The PartialSchedule or Schedule only has information about generally when future instances of this session will take place. There are exceptions to these rules and so it should be made obvious to customers that these dates are not guaranteed.

OpenActive also recommends this. In its Modelling Specification, it says that consideration should be given to how information pertaining to a PartialSchedule is displayed to the end user: “data consumers should consider how to present this information in a way that will make it clear to end users that the event details may be subject to change”.

An EventSeries can contain the following data:

• Only a ScheduledSession;
• Both a ScheduledSession and PartialSchedule / Schedule; or
• Only a PartialSchedule (lease common).

Note

In the event that an EventSeries contains both a ScheduledSession and PartialSchedule / Schedule, we recommend that you either:

• Only show date/time information from the ScheduledSession (which is the guaranteed time that the session will occur). Showing both pieces of information could result in a confusing UX if it is not clear to the user that the PartialSchedule / Schedule information is not a guarantee.

• With care, show information from both the ScheduledSession and PartialSchedule / Schedule. If the information is clearly rendered in a way that shows that:

  • The ScheduledSession time is when this particular instance of the session is guaranteed to start.
  • The PartialSchedule / Schedule time is when future instances of the session may start.

  Then, the user will get the benefit of knowing more about the session, which will help them decide if it’s the right one for them (e.g. “perhaps I’ll come regularly if I like it. I can’t always make the Tuesday but look - they have sessions on Thursdays too!”).

PartialSchedule vs Schedule

The items in a SessionSeries’ eventSchedule array can be either PartialSchedules or Schedules. For front-ends, the difference isn’t important but it may interest you regardless.

• Schedule: has a lot of date/time information - OpenActive dictates that Schedules must have certain fields (see required properties). Internally, imin generates ScheduledSessions from Schedules where they exist as well as exceptions and amendments, which come from other sources.
• PartialSchedule: has less date/time information - OpenActive only mandates for the inclusion of @type (see the required property). For example, they may be missing an endDate. Internally, imin does not generate ScheduledSessions from PartialSchedules and instead gathers them from other sources.

Note

Regardless of the type - Schedule or PartialSchedule, they should be treated the same by a front-end - as a rough guide to future occurrences.

Timezones

Because a Schedule / PartialSchedule can occur over timezone boundaries (e.g. it may occur on the week before clocks go forward and the week after), it cannot have a single timezone designator (e.g. 12:00Z would refer to 12:00 before clocks go forward and 13:00 after).

This is why the scheduleTimezone field is included, which specifies the IANA time zone. When not included, please assume that this field is set to Europe/London.

To render the correct time in JavaScript, you can use Moment Timezone. For example:

> const moment = require('moment-timezone');
> const schedule = { /** with the PartialSchedule defined above */ }
> const datetime = moment.tz(
  `${schedule.startDate} ${schedule.startTime}`,
  'YYYY-MM-DD HH:mm',
  schedule.scheduleTimezone || 'Europe/London');
// Render the time using the appropriate timezone designator
> datetime.format();
'2019-07-01T12:00:00+01:00'
// You can also convert it to UTC if you wish
> moment(datetime).utc().format();
'2019-07-01T11:00:00Z'

Note

For more information about schedules, please refer to the OpenActive Developers pages: Schedule and PartialSchedule.