Activity list references
Last updated
Last updated
In order to allow your data to be easily searchable across a wide range of applications, it must contain references to the .
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.
A of the OpenActive Activity List is available for live integration into applications, together with a for navigating the list.
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 for the activity provider to select from when they are creating or updating an opportunity in the booking system.
In the relevant , the @id and prefLabel of at least one activity from the OpenActive Activity List must be included with each opportunity, along with an inScheme of "https://openactive.io/activity-list", as shown below:
See for a full feed example that references the OpenActive Activity List using the snippet above.
Please note that although the newer @id and @type are used here and throughout the rest of the OpenActive documentation and tooling, the OpenActive Activity List JSON-LD definition itself still uses id and type for 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.
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 Accept header, and is cached via CDN.
Note: there is no www in the URL.
Within your application, it is advisable to store the full @id of an OpenActive Activity List Concept against each opportunity in your database, as the prefLabel and other properties are likely to change over time.
Your application may also store the prefLabel alongside the @id at the point of the associating an OpenActive Activity List Concept with 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 prefLabel when rendering the open data it receives.
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.
id
The unique ID of the Concept, which should be stored and used when referencing the Concept.
Yes
prefLabel
The primary display label for the Concept, in the English language.
Yes
altLabel
The alternative display labels of the Concept, in the English language. When displaying the Concept to the user it is recommended that the array of altLabel be appended to the prefLabel, using the separator " / ". This logic does not apply to the prefLabel included in the open data feed.
No
topConceptOf
Indicates that the Concept is at the top level of the hierarchy, when the value of this property is equal to "https://openactive.io/activity-list".
No
broader
No
narrower
An array of child Concept IDs.
No
To render a hierarchy:
Filter the data to return only Concepts with topConceptOf set to "https://openactive.io/activity-list", to produce an initial list of top-level Concepts.
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 @id to set the dropdown to an existing value.
On selection the dropdown provides both @id and prefLabel, which can then be stored in your database and later used within your open data feed(s).
The dropdown also provides an activity definition that 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.
This is usually achieved by adding additional fields "OpenActive @id" and "OpenActive prefLabel" to your existing activity types table, and providing a in your activity type editor.
This 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.
If your booking system is restricted to a small number of different activities (e.g. is restricted to just "Running"), it is usually better to hardcode the activity list references into your booking system.
To find the @id simply , 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.
We recommend using 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.
Although the use of is recommended when reading the JSON-LD definition of the OpenActive Activity List in JavaScript, for other languages the JSON-LD may also be parsed directly.
The of the OpenActive Activity List includes the following key properties:
An array of parent Concept IDs. Note this is a list, and the same Concept may exist under multiple parents.
For general contribution simply link to "". This will take the user to a page where they can make suggestions about the activity list.
Example:
Example:
