Proposal to recommend more specific Types of Event

[nickevansuk]

In order to more clearly distinguish between different type of Event, we could move towards a recommendation of only using the most applicable type of Event as the parent event.

Specifically:

Session

A Session with subEvent containing an array of Event

• The parent event is a "Session" to distinguish it from other types of event
• Session is a more specific type of Event

Course

A Course with hasCourseInstance containing an array of CourseInstance

Facility

A FacilityProduct with hasTimeslots containing an array of Timeslot

• Timeslot is a more specific type of Event
• FacilityProduct is a more specific type of Product

Online Class

A BroadcastEvent for online sessions with subEvent containing an array of Event

League

A League with hasFixtures containing an array of SportsEvent

• It may not be relevant to represent individual fixtures, as ringers are relevant to the event itself
• League is a more specific type of EventSeries

[ldodds]

Handling these in turn

Session

We had a lot of debate about use of the term "session" during the early stages of the standards work. We eventually agreed that session and Event are synonymous. The term is ambiguous though. For example my understanding of session is that it is a specific instance of an event in a series, rather than something that will have sub events as you've outlined.

My suggestion is that if there's a need to distinguish between Events that will always have more detail in sub events, then we define a type for that. However the pending Schema.org EventSeries is also applicable.

Course

The course is a creative work, with the instance being a specific time that the course is run. That might be a single Event (a one day course) or a series of events (e.g. over a semester, summer, etc).

We might need to identify Courses and events related to them, but suggest we have a wider discussion on this.

Facility

This is covered by the facility proposal in #62. It is a product (oa:AmenityUse) with an array of events. I don't think there's a need for a new TimeSlot type.

Online Class

This could work as described. But again, would like to have a wider discussion about this type of Event. Presumably there will be specific information required, e.g. about how to participate, find it online, etc.

League

Can be handled via the pending EventSeries property. Spaces for ringers can be handled using the existing availability properties.

There's some broader considerations here:

• Whether there are some recurring patterns around grouping of Events, e.g. Programmes, Courses, etc
• Whether we need to more clearly distinguish between Events that always have detail in subEvents (which is a common case)
• Whether we are going to use subTypes of Event, and if so, do we expect clients to understand them all, or whether we should clarify that a JSON-LD object can have multiple type properties. This might better support consumers in handling unexpected types
• What additional properties or requirements are associated with describing each sub-type.

[lukehesluke]

@ldodds Just to add to your comment about "Session":

• For the kinds of data we've come across at imin, it would be very useful to have a specification for an Event with mandatory detail in subEvent
• Perhaps a little more controversial, but it may also be useful to draw a line between Events that have exactly one subEvent item ("one-off" events) and events which have 1+ subEvent items ("recurring" events). Obviously in terms of data structure, "one-off" events are a subset of "recurring" events, but there is a difference in how these events are interacted with:
  • In a search API, "sort by start date" has one clear definition for "one-off" events and is either invalid or nuanced in what it means for "recurring" events (sort by first subEvent item? Last? Average?)

[nickevansuk]

Note for Courses, the CourseInstance event can be easily used instead of Event at the top level to distinguish regular sessions from Courses. To @ldodds's earlier point, the Course is the info about the course, not the instance of the course itself. The subEvents are the different sessions within a particular CourseInstance (i.e. a course that runs over a number of specific weeks)

[nickevansuk]

Validation rule note for when this proposal makes it through: there should be at least one Offer on the "CourseInstance" that allows a user to book onto the course in its entirety

[ldodds]

Have revised the comments and here is what I'm proposing we add to the 2.0 specification. Let me know what you think

• We define a new sub-type Session which is an instance of an Event in a schedule
• We use EventSeries to indicate an event that will have multiple instances, e.g as specified by an eventSchedule property.
• We use CourseInstance for instances of a course. The individual classes will be Events.
• We continue to allow Events to have subEvents, but these are to link shorter Events that are part of a full or multi-day event.

So we end up with:

• Event -subEvent-> Event -- full day events, multi-day events, festivals linking to items in their programmes.
• EventSeries -(subEvent)-> Session -- recurring classes linking to individual sessions (tonight's class)
• EventSeries -(schedule)-> Session -- clarify that schedules generate Session events
• CourseInstance -(subEvent)-> Event -- term of lessons linking to individual lessons

I think this covers the majority of requirements including those suggested by @lukehesluke. Noting that Facilities are now handled differently and Online Classes are part of the Virtual Events proposal (#71).

Leagues might just be EventSeries.

We also need to clarify some of the rules around "inheritance" of properties from parent to subEvents.

• For EventSeries I think a Session could inherit all properties, including Offers.
• For CourseInstance a sub-event Event could inherit all properties, except Offers (courses are likely to be priced differently to individual classes if they even have prices at all)
• Same for Events that are parents of other Events. There will likely be different properties for the whole Event than parts of it.

So EventSeries is just the special case where we inherit offers.

Inheritance would be defined as, a consumer could use information from the parent object (e.g. name, description, images, etc) unless the subEvent defines the same property, in which case its value overrides the parent.

We can also some define additional conformance criteria, e.g.

• Event -subEvent-> Event -- the child event should have a start/end time with parent.
• EventSeries -(subEvent)-> Session -- the EventSeries should have a schedule or at least one subEvent?
• Session should have a parent event?

Thoughts?

[nickevansuk]

This is very nice indeed!

Some thoughts:

• Should CourseInstance -(subEvent)-> Event instead be CourseInstance -(subEvent)-> Session? Or something else more specific? Seems strange to go from specific to generic?
• There are still feeds (e.g. British Cycling) which essentially consist of ad-hoc sessions, which means we can't always guarantee a parent event.
• the child event should have a start/end time with parent., perhaps not always as with British Triathlon the subEvents are types of Event (e.g. "Aquathlon Sprint") that are part of the overall Event (e.g. "Big South East Aquathlon")
• We probably want to distinguish a League from an EventSeries that includes Sessions, as leagues wouldn't consider Events with the league as sessions (they usually have multiple games with various kick-off times during an evening). So League -> Event -> Game? Noting that League is likely to have defined things like "maximumTeamCapacity" and "remainingTeamCapacity" as well as individual spaces available.

I wonder if it's worth breaking Leagues out into a separate proposal here and getting some focussed attention on it?

[nickevansuk]

Also note we need to think about how this works for VirtualEvent / OnlineEvent (https://github.com/openactive/modelling-opportunity-data/issues/71)

[nickevansuk]

Also assume in the above that ad-hoc sessions (e.g. Let's Ride rides) are just top level Sessions, without an EventSeries?

[ldodds]

+1 to breaking out Leagues into separate proposal and discussion, there's much more to cover and would be better to make all related changes in one go.

This is also consistent with our approach to Virtual/Online Event too.

For ad-hoc sessions, I think these are just Events not Sessions. A Session would be explicitly defined as being generated from a Schedule.

[nickevansuk]

Noting that not all EventSeries which contain Sessions will have a schedule that can be used to generate them (e.g. with cycling events the Sessions which do occur within an EventSeries are ad-hoc)?

Should the naming of Session be something in line with schema.org, e.g. PhysicalActivityScheduledEvent? (all schema.org Event subclasses have the "Event" postfixed)

Keeping in mind https://github.com/openactive/modelling-opportunity-data/issues/117 and the request for consistency, does it make sense to also use PhysicalActivityScheduledEvent for ad-hoc too if we change the name, to reserve Event for full day events, multi-day events, festivals linking to items in their programmes as above?

[ldodds]

Currently debating whether a CourseInstance can have an eventSchedule. Any thoughts @nickevansuk? Seems like this would be a useful way to indicate, e.g. 10 weekly classes without having to itemise them all via subEvent.

This would mean that a Session might have parents of different types. But, as it doesn't make sense to inherit offers from some types of Event we need to consider that. For example for a CourseInstance you pay to attend the course not classes.

So then the conformance rule would be that Sessions would inherit only some properties from its parent. Consumers will need to check the parent type to decide which ones to inherit. E.g. if the Session is part of an EventSeries then it would inherit all properties, but only some (e.g. location but not offers) if the superEvent is a CourseInstance.

An alternative approach is to indicate in a Schedule which type of Event is being generated when expanding it into individual instances. Then a CourseInstance schedule might generate Events, whereas an EventSeries would generate Sessions.

This would mean adding something like the following to Schedules:

{
 "@type": "Schedule",
 "instanceType": "Session"
}

I think I prefer this, because it means that the description of inheritance rules is tied specifically to the sub-type. e.g. A Session will inherit Offers from its parent.

This also feels safer as the default processing rule for all Events would be that offers are not inherited bt default. This means a consumer encountering new sub-types won't accidentally take a user into a booking workflow with incorrect offers. A consumer understanding the definition of a new type can then apply any additional logic.

Adding instanceType and allowing eventSchedule to continue to be used more broadly, also gives more future flexibility around online events, etc.

Any thoughts?

[ldodds]

@nickevansuk can you give an example of this:

Noting that not all EventSeries which contain Sessions will have a schedule that can be used to generate them (e.g. with cycling events the Sessions which do occur within an EventSeries are ad-hoc)?

If they are ad-hoc events (which I'm reading as occasional events) then they don't seem like they are part of a series to me. They may be run by same organisation, or part of same Brand, but not a series.

I'm fine with using as an alternative name although PhysicalActivityScheduledEvent is quite a mouthful!. It would be part of the definition that this is a scheduled event. so PhysicalActivitySession seems clearer. Keeping "Session" aligns with how we're already using that term in the spec and discussions.

I'm not sure what you mean by consistency with #117. I think this proposal completely supercedes it and brings consistency to how start/endDate and schedules are described. #117 also seems to be based on a misunderstanding (limits on how state/end date are used) and is encouraging use of subEvent in all cases which is also not what we're discussing here.

[nickevansuk]

Yes think that CourseInstance should have an eventSchedule, as will reduce the need to generate subEvents if the publisher doesn't store the data with that granularity.

Adding instanceType is a great plan, allows for more flexibility in future, and makes expected behaviour to data consumers much simpler.

In terms of the types used for individual occurrences, the primary benefit of using specific descriptive types is that it makes it much easier for data users to render them correctly to consumers. To this end, suggest that switching on the parent type should be preferred to indicate what the user expects, and that the subEvent type should be more descriptive of the inheritance pattern expected.

The other benefit is that data users may well want to filter out Event types that they're user interface doesn't support, or specifically design for a restricted set of data to be displayed for these. E.g. below a data user may have an interface to display regular sessions such as Yoga classes or Triathlon club training evening, and wouldn't want to misrepresent a full-blown Triathlon event and its subEvents within the same interface, so would perhaps just display the headline details of the Triathlon EventCollection and ignore the subEvents.

eventSchedule and instanceType

An eventSchedule will only generate "subEvents" if instanceType is specified, otherwise it can simply be used to specify data related to the regularity of the session, such as dayOfWeek (see here for example), without creating subEvents - for situations where subEvents are specified explicitly. See here for an existing example: https://everyoneactiveuat-openactive.azurewebsites.net/api/sessions

For this reason, perhaps instanceType should be renamed generatedInstanceType?

Usecases

The below usecases are reflective of data that we are currently aware of:

Regular Sessions

This is an event (usually 1 or 2 hours in duration), that happens with some regularity. It is expected that if a user attends one of these events, that they would find another event in the series happening soon afterwards. They are not just attending a one-off event, as there is an implication of also being part of a community of regular attendees. Note that although the events might be frequent, they do not necessarily conform to a rigid Schedule (though many do). For example click the "Rides" tab in this group https://www.letsride.co.uk/groups/central-london-outdoor-group there is no regularity here.

The key thing that distinguishes a Regular Session from the more general EventSeries is that it's a thematic event series (e.g. topical meetup or class), or a series of regular events that share a location, attendee group and/or organizers, at a frequency that a participant can expect to build a real exercise habit (at least monthly, as a guide).

The Olympic Games (taken from the schema.org description text) or London Marathon would not be considered a Regular Session, event though they would be considered an EventSeries by the schema.org definition.

Suggestion:

• SessionSeries as a subclass of EventSeries
• Session as a subclass of Event
• SessionSeries -(subEvent)-> Session
• Session can be used alone for ad-hoc sessions that are not part of an Event
• Offers are inherited from SessionSeries to Session
• Session -> (superEvent) -> SessionSeries can be used for loosely defined series where each session is more unique (https://www.goodgym.org/areas/barnsley/happenings/group-runs) - noting that eventSchedule defined in this context will likely not be configured to generate subEvents.
• SessionSeries should be displayed alongside the upcoming Session (e.g. this week's session), and details of it's recurrence ("Tuesday" if the schedule indicates it's every Tuesday), with the expectation the user is most likely to want to book onto a session that's near to now. If photos and a description of the next session are available these should also be displayed prominently.

Mass Participation Events

These are large scale events such as London Marathon or a Triathlon "Hebridean Cycle Challenge", which are typically all day with specific start times for subEvents happening within them.

For example, the "Big South East Aquathlon" contains "Big South East Aquathlon Long Course", "Big South East Aquathlon Sprint", "Dartford Bridge Aquathlon". All these events happen together, or at offset times during the day. The same is true of any marathon or half-marathon, which might include different races such as the "Elite Wheelchair Marathon"

Suggestion:

• EventCollection as a subclass of EventSeries
• EventCollection -(subEvent)-> Event
• Event can be used alone for ad-hoc mass participation events.
• offers are not inherited from EventCollection to Event
• Events within an EventCollection are expected to be displayed alongside the description of EventCollection, with no expectation of any regularity or ordering within them (e.g. not just displaying "next week's session")

Courses

A course can be booked on at once, and offers from a CourseInstance should not be inherited by a CourseEvent.

As above, to ensure correct rendering of these and correct inheritance, CourseEvent should be defined as a subclass of Event with specific inheritance behaviour.

Suggestion:

• CourseEvent as a subclass of Event
• CourseInstance -(subEvent)-> CourseEvent
• CourseEvents must always exist in the context of a CourseInstance.
• CourseEvents do not inherit offers from a CourseInstance.
• CourseEvents within an CourseInstance are expected to be displayed alongside the description of CourseInstance, with it made clear that the user is signing up to the whole course and not to individual sessions (unless offers are also available on individual sessions).

ScheduledEvent (subclass EventSeries): expect a number of child Events

Catchall "Event" (for other usecases yet to be defined)

For types of event that are not yet handled in the specification, they can be published using the generic "Event" type.

Suggest for these, the inheritance behaviour remains undefined, and data users are advised to handle these on a case-by-case basis rather than making assumptions about offers or booking.

The default expected rendering for these events by data users is just to render the details of the Event as an individual Event, and not to try to elaborately display subEvents, as their relationship and inheritance is undefined.

So e.g. if a League was to be represented as an Event (before League is defined by the spec), the expected behaviour would be to render the Event complete with links to the url property and the pricing in its offers object, blindly displaying its start and end time (which would be the dates of the start and end of the whole season) but ignore any subEvents (which are likely to be the games within the league) rather than trying to render them as "next week's session", as a participant will need to join a league for the whole season not just turn up at sessions.

[nickevansuk]

Noting that from the OpenActive website, this discussion now covers:

• Events / Mass Participation Events
• Regular Sessions
• Courses

The following are covered (or will be covered) elsewhere:

• Facilities
• Leagues and Ringers
• Routes
• Online / Virtual Classes

[nickevansuk]

Additionally to the above, there is one further use case that has not been included:

Grouping Events

For Events, Regular Classes (SessionSeries), and CourseInstances, there is usually a large amount of commonality between instances of the same type of Event, SessionSeries, or CourseInstance, which is useful to describe as an object which links these together.

The reason for this is that in discovery mode the end user cares more about understanding the distinct opportunities that are available than they do about browing directories with duplicate events held at different locations. Such a high level object would likely include detail on the event, description, images, video, level, as well as potentially offers.

This will prevent duplicates in search results as below and allow the user to have a more streamlined experience, as well as increasing the usability of the data overall:

The CourseInstance already has the Course type for this purpose, which is related to CourseInstances.

Proposal

Use of types:

• We should allow EventSeries to be used to group both Events and SessionSeries.
• We should allow Course to be used to group CourseInstances (as schema.org already allows).

Inheritance:

• Offers of EventSeries are inherited via subEvent for both SessionSeries and Event
• Offers of Course are inherited via hasCourseInstance for CourseInstance.

Conformance:

• superEvent within SessionSeries should be a recommended property
• superEvent within SessionSeries MUST only contain EventSeries
• EventSeries has subEvent which may contain SessionSeries or Event
• id within EventSeries is required if embedded via superEvent
• id within Course is required if embedded via hasCourse

Additional properties for OA namespace:

• hasCourse should be defined on CourseInstance as the inverse of hasCourseInstance.

Worked Example

The screenshot below shows how this relationship works within GoSweat (who use their own non-OpenActive data sources):