ScheduledSessions and eventSchedules

An Introduction to the SessionSeries subEvent

In each SessionSeries, there are two fields that determine when a session can occur:

1. subEvent[] containing ScheduledSessions, which are normally present for each item and deemed to be authoritative, i.e. the session is guaranteed to take place at this time.

2. The eventSchedule, which can include a Schedule or PartialSchedule. These have more general information useful for supplementing the ScheduledSession. They are not necessarily deemed to be authoritative, i.e. the session may take place at this time.

A SessionSeries can contain the following data:

• Only a ScheduledSession (with or without an eventSchedule); or

• Only a PartialSchedule (least common).

A ScheduledSession has information about exactly when a session is going to take place.

An eventSchedule can be used to supplement the ScheduledSessioninformation displayed to the end user.

If a ScheduledSession is not present, caution should be exercised when presenting PartialSchedule information to the end user as it only tells us that a session might take place in the future.

Top tip: if there are ScheduledSessions, any information within the eventSchedule (if present) can be considered supplemental. Only if there are no ScheduledSession should the PartialSchedule included in the eventSchedule be used to display non-authoritative information about session timings.

ScheduledSessions

Generally speaking, most SessionSeries in our data will will include, at a minimum, a ScheduledSession. These objects will include information about exactly when a session is going to take place. It should be considered to be the source of truth when it comes to a session's scheduling information.

Example

"subEvent":[
   {
      "url":"https://www.thisisanexample.com",
      "type":"ScheduledSession",
      "endDate":"2021-06-07T09:00:00Z",
      "duration":"PT1H",
      "startDate":"2021-06-07T08:00:00Z",
      "identifier":"https://thisisanexample.com/[...]/2021-06-07T08:00:00Z",
      "id":"https://search.imin.co/events-api/v2/scheduled-sessions/https%3A%2F%2Fthisisanexample.com%2F%5B...%5D%2F2021-06-07T08%3A00%3A00"
   }
],

ScheduledSessions and EventSchedules

Where an EventSeries includes a ScheduledSession, you can treat this as authoritative and can, in theory, disregard any other scheduling information, including the EventSchedule.

You can present ScheduledSessions to the end user on the front as authoritative, i.e. they are definitely taking place.

However, the EventSchedule can be used to supplement the information provided to the end user to improve the UX.

The eventSchedule

The items in a SessionSeries'seventSchedule array can be either take the form of a Scheduleor a PartialSchedule and this is dictated by the open data we receive from different providers. As a user of our data, the difference isn't incredibly important, but it may interest you nonetheless.

Why do we have Schedules and PartialSchedules?

Schedules

Where an open data provider does not provide ScheduledSessions, they might instead provide Schedules from which we at imin can generate ScheduledSessions. We do this because they are required to have certain date/time information (see OpenActive's required properties ). It is because of this that Schedules include information can reasonably be relied upon by the end user.

Internally, imin generates ScheduledSessions from Schedules where they exist, as well as exceptions and amendments. This means there where there is a Schedulein an EventSeries, there will always be a ScheduledSession.

PartialSchedules

Some open data providers will have neither a dedicated ScheduledSession feed (authoritative information), nor will they provide Schedules information that allows us to generate ScheduledSessions. Instead they might provide PartialSchedules, which contains insufficient information for our Platform to generate ScheduledSessions. This is because OpenActive only mandates for the inclusion of @type (see required property), which means that a PartialSchedule generally does not have an endDate nor a repeatCount.

Internally, imin does not ever generate ScheduledSessions from PartialSchedules. This includes in the ByID route.

The presence of a PartialSchedule does not automatically mean that there will be no ScheduledSession. This is because a provider of open data can include have a dedicated ScheduledSession feed and also include PartialSchedule information in their SessionSeries feed.

For more information, please refer to the OpenActive Developers pages for Schedule and PartialSchedule.

What do Schedules/PartialSchedules look like in our data?

Schedules

"eventSchedule":[
   {
      "type":"Schedule",
      "byDay":[
         "schema: Thursday"
      ],
      "endDate": "2021-05-31",
      "endTime":"10:15",
      "duration":"PT1H",
      "startDate": "2021-05-17",
      "startTime":"09:15",
      "repeatFrequency":"P1W",
   }
   {
      "type":"Schedule",
      "byDay": [
         "schema:Monday",
         "schema:Tuesday",
         "schema:Wednesday",
         "schema:Thursday",
         "schema:Friday"
      ],
      "endDate": "2021-05-31",
      "endTime":"19:30",
      "duration":"PT1H",
      "startDate": "2021-05-17",
      "startTime":"18:30",
      "repeatFrequency":"P2W",
   }
],

PartialSchedules

"eventSchedule":[
   {
      "type":"PartialSchedule",
      "byDay":[
         "schema: Thursday"
      ],
      "endTime":"10:15",
      "duration":"PT1H",
      "startTime":"09:15",
      "repeatFrequency":"P1W",
   }
   {
      "type":"PartialSchedule",
      "byDay": [
         "schema:Monday",
         "schema:Tuesday",
         "schema:Wednesday",
         "schema:Thursday",
         "schema:Friday"
      ],
      "endTime":"19:30",
      "duration":"PT1H",
      "startTime":"18:30",
      "repeatFrequency":"P2W",
   }
],

Displaying Schedules and PartialSchedules on the front end

As a rule of thumb, Schedule/PartialSchedules information in our APIs should be approached with caution. This is because the information is limited to such an extent that it is only possible to say that a session might be taking place, e.g. the instructor might be ill or the session falls on a Bank Holiday.

Regardless of the type - Schedule or PartialSchedule- both objects should be treated the same when it comes to displaying on front end: as a rough guide to future occurrences.

Where there is a ScheduledSession present

As noted above, the ScheduledSession should always be used as the authority when displaying information to the end user as it is guaranteed to take place at this time. However, the Schedule/PartialSchedule does offer helpful information that can supplement the ScheduledSession to further inform the user.

How a ScheduledSession and an eventSchedule can be rendered to help end users

Displaying the Schedule/PartialSchedule information can be useful because all future ScheduledSessions may not be available to you to present to the end user due to our 2-week API Lookahead Window.

You should not extrapolate based on the information found in the eventSchedule and communicate to the end user that a session will definitely take place, e.g. every Tuesday and Thursday, as the future ScheduledSessions may tell us otherwise.

Where there is not a ScheduledSession present

Where a ScheduledSession is not present and instead only a PartialSchedule, we recommend using the data included in the eventSchedule to render it on the front end and use a pop-over to explain to the end user that the session information should be referred to, but not relied upon, with the best course of action being for the end user to contact the session organiser to check it is taking place.

If you are presenting PartialSchedule information to the end user and there is no ScheduledSession, it should be made abundantly clear that:

• The sessions are not guaranteed to take place; and

• They should contact the organiser to find out whether it is taking place or not.

OpenActive also recommends taking this approach, noting in its Modelling Specification 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.

For more information on displaying information from an EventSchedule on a front end, please see our page on UX tips here.

Time Zones For eventSchedules

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

This is why the scheduleTimezone field is included, which specifies the IANA time zone.

The scheduleTimezone field will not always be included. When it is not, 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'