Comment on page
Activity list references
The OpenActive Activity List is a standardised hierarchical list of physical activity types. It includes over 600 entries, each of which have a unique identifier in the form of a URL.
Each opportunity within a booking or listing system must have an associated activity from the OpenActive Activity List. This is often achieved by providing a dropdown list for the activity provider to select from when they are creating or updating an opportunity in the booking system.
In the relevant open data feed, the
prefLabelof at least one activity from the OpenActive Activity List must be included with each opportunity, along with an
"https://openactive.io/activity-list", as shown below:
Please note that although the newer
@typeare used here and throughout the rest of the OpenActive documentation and tooling, the OpenActive Activity List JSON-LD definition itself still uses
typefor backwards compatibility.
A booking system may choose to allow an opportunity to include multiple references to the OpenActive Activity List. If such a feature is implemented, a limit on the total number of references permitted per opportunity is recommended to discourage "tag spamming" (for example, a maximum of 3).
An example of multiple references to the OpenActive Activity List is shown below:
If your booking system already has "activity types" available from a controlled list, these existing activity types should be mapped to the OpenActive Activity List.
This OpenActive Activity List JSON-LD definition SHOULD be retrieved at least nightly using an HTTP GET and cached within an application. This ensures that the most up-to-date version is displayed to the user, while also protecting against network failure when accessing the underlying resource.
To access the JSON-LD definition the application MUST GET the URL
"https://openactive.io/activity-list/activity-list.jsonld"which does not require a specific
Acceptheader, and is cached via CDN.
Note: there is no
wwwin the URL.
The JSON-LD definition is also available via a GET of the URL
application/ld+json, to conform with JSON-LD expectations, however this shorter URL MUST NOT be used in production.
Within your application, it is advisable to store the full
@idof an OpenActive Activity List
Conceptagainst each opportunity in your database, as the
prefLabeland other properties are likely to change over time.
Your application may also store the
@idat the point of the associating an OpenActive Activity List
Conceptwith an opportunity, to remove the need to reference the activity list while outputting open data. It is the responsibility of the data user to use the latest
prefLabelwhen rendering the open data it receives.
If your booking system is restricted to a small number of different activities (e.g. Run Together is restricted to just "Running"), it is usually better to hardcode the activity list references into your booking system.
To find the
@idsimply find the relevant activity in the OpenActive Activity List, then scroll down to the bottom the page to view a full example JSON-LD snippet for that specific activity, such as the screenshot below. This can be included in your open data feed.
Screenshot of full example JSON-LD snippet from OpenActive Activity List website
We recommend using SKOS.js to implement any activity list client-side rendering, to allow your users to select an activity from a hierarchical representation of the OpenActive Activity List to associate with an opportunity.
Maintaining the hierarchy and providing a typeahead search is important as with over 600 activities, and with many activities being more general terms, using an ordinary dropdown box becomes unwieldy for the user.
To render a hierarchy:
- 1.Filter the data to return only Concepts with
"https://openactive.io/activity-list", to produce an initial list of top-level Concepts.
- 2.Recursively, for each Concept, lookup the
narrower(child) Concept IDs.
Below is a copy-and-pastable example of a searchable hierarchical dropdown that can be used within your booking system to allow the user to select an activity from the OpenActive Activity List.
On load you may specify the
@idto set the dropdown to an existing value.
On selection the dropdown provides both
prefLabel, which can then be stored in your database and later used within your open data feed(s).
The dropdown also provides an activity
definitionthat may be displayed to the user for disambiguation.
See the "Result" tab below for a live demo.
An example of the above code in the Our Parks booking system is shown in the video below.
Note "OpenActive id" and "OpenActive prefLabel" fields are displayed in the video for debugging purposes, but would ordinarily be hidden from the user.
It is recommended that you provide links to contribute to the OpenActive Activity List, which encourage activity providers to participate in its maintenance and curation.
Two different types of links are available:
The link to contribute to a specific activity is simply the URL of the
@id. This will take the user to a page specific to the activity where they can make suggestions about the activity, including updating the definition of an activity.
An example of "Contribute" links within the Gladstone leisure management system is shown below.
Screenshot of the "Contribute" links within the Gladstone system