nickevansuk
commented
5 years ago Primary Issue
Issue Description
Without providing a means of grouping the Events, the nature of Upshot's creation of "X sessions at the same time" will currently cause a large volume of what will appear to be duplicate data to be surfaced (i.e. a large volume of Events that vary on date/time alone, without any other variance between them). This makes the data substantially less useful, and therefore much less likely to be used by data consumers.
Background
This draft document explains the various types of groupings available within the OpenActive V2.0 model: https://docs.google.com/document/d/1C_eO6JC8tt7-K-XiilHzPKXKenjjHiiOS7nCW07tlLk/edit
Observations
- Upshot's internal model includes activities, which seem to be a kind of "parent"/"template" as they include a description and represent part of the session's title in the calendar.
- Upshot's sessions do not have descriptions. They are tied to activities that have an optional description field
Suggested solution
SessionSeries and ScheduledSession should be used, as this is the best fit for the type of regular sessions often captured in Upshot, and Event used for purely ad-hoc sessions.
Based on the above, we suggest the best solution is pulling the upshot "activity" out into an EventSeries and using the "inverse" representation via superEvent to minimise changes to the feed at this stage.
The following are recommended for the two different types of Upshot sessions:
1) For generated sessions: ScheduledSession -> SessionSeries -> EventSeries
This assumes that when organisations add recurring sessions with a specified frequency and a total of sessions, that there is some common key that links the generated sessions together - e.g. to allow them to be updated in bulk later. This would be the "SessionSeries" identifier. SessionSeries can be used without an eventSchedule at this stage to indicate the grouping of ScheduledSessions, and the eventSchedule can be added later via e.g. deriving a recurrence pattern as you suggest.
If the location can't be included in the SessionSeries it should be included in the ScheduledSession.
Note there is a known bug in the validator: it does not recognise property inheritance across three levels, which causes errors for the below.
{
"id": "62bd8efa62d89270",
"state": "updated",
"kind": "ScheduledSession.SessionSeries",
"modified": 1541072820473428,
"data": {
"@context": "https://openactive.io/",
"type": "ScheduledSession",
"identifier": "62bd8efa62d89270",
"name": "OpenActive QA - Recurring session (concat to match calendar title)",
"startDate": "2018-09-22T08:15:00Z",
"endDate": "2018-09-22T08:30:00Z",
"duration": "PT15M",
"eventStatus": "https://schema.org/EventScheduled",
"superEvent": {
"type": "SessionSeries",
"identifier": "recurrenceGenerationId?",
"location": {
"type": "Place",
"url": "https://staging.pitchfinder.org.uk/",
"name": "Torchbox Bristol",
"address": {
"type": "PostalAddress",
"streetAddress": "15 Colston st",
"addressLocality": "Bristol",
"addressRegion": "Test",
"postalCode": "BS1 5AP",
"addressCountry": "GB"
},
"geo": {
"type": "GeoCoordinates",
"latitude": 51.4554436314615,
"longitude": -2.59774495378551
}
},
"superEvent": {
"type": "EventSeries",
"identifier": "activityId?",
"name": "OpenActive QA",
"description": "Activity description",
"organizer": {
"type": "Organization",
"name": "OpenActive Test"
},
"activity": [
{
"type": "Concept",
"prefLabel": "OpenActive QA"
}
],
"url": "https://staging.upshot.org.uk/calendar/sessions/31049376/#calendar/2018-9",
"category": [
"Social events"
]
}
}
}
}2) For ad-hoc events: Event -> EventSeries
Although this is easier to achieve, it must be noted that it is technically inaccurate to represent generated sessions this way, as the generated sessions are not actually ad-hoc events (they are generated from a recurrence pattern). Some data users (e.g. Classfinder) do not consume Events in this format as it is usually reserved for Race for Life events etc, and those data users that do will likely not expect a large volume of recurring sessions generated from a schedule to be represented this way. See here for more info: https://developer.openactive.io/data-model/data-model-overview.
Note however that truly ad-hoc events (i.e. those that are not generated from a schedule) should be presented like this.
A mix of "Event" and "ScheduledSession.SessionSeries" kinds can easily be included in one feed, which will allow Upshot to represent both generated and ad-hoc sessions.
{
"id": "62bd8efa62d89270",
"state": "updated",
"kind": "Event",
"modified": 1541072820473428,
"data": {
"@context": "https://openactive.io/",
"type": "Event",
"identifier": "62bd8efa62d89270",
"name": "OpenActive QA - Recurring session (concat to match calendar title)",
"startDate": "2018-09-22T08:15:00Z",
"endDate": "2018-09-22T08:30:00Z",
"duration": "PT15M",
"eventStatus": "https://schema.org/EventScheduled",
"location": {
"type": "Place",
"url": "https://staging.pitchfinder.org.uk/",
"name": "Torchbox Bristol",
"address": {
"type": "PostalAddress",
"streetAddress": "15 Colston St",
"addressLocality": "Bristol",
"addressRegion": "Test",
"postalCode": "BS1 5AP",
"addressCountry": "GB"
},
"geo": {
"type": "GeoCoordinates",
"latitude": 51.4554436314615,
"longitude": -2.59774495378551
}
},
"superEvent": {
"type": "EventSeries",
"identifier": "activityId?",
"name": "OpenActive QA",
"description": "Activity description",
"organizer": {
"type": "Organization",
"name": "OpenActive Test"
},
"activity": [
{
"type": "Concept",
"prefLabel": "OpenActive QA"
}
],
"url": "https://staging.upshot.org.uk/calendar/sessions/31049376/#calendar/2018-9",
"category": [
"Social events"
]
}
}
}Other feedback
- ScheduledSession.name and Event.name should match the title in the calendar i.e. by concatenating the activity name with a "-". EventSeries.name is just the activity name.
- Properties with null values should not be included.
- If
offersare not available,offersshould not be included rather than priced at zero - as zero inaccurately indicates that the sessions are free. The get Upshot to validate without errors, accurate pricing data will need to be captured.
zerolab
Open endpoint for QA:
-- AND / OR --
Sample JSON:
A few notes: