Copyright © 2025 the Contributors to the OpenActive Club Specification, published by the OpenActive Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.
This specification describes a simple data specification to support the standardised publication of organisation or club data. It aligns with the OpenActive data model for opportunities for people to engage in physical activities ("opportunity data"), which includes description of activities, as well as the events and locations in which they take place.
OpenActive specifications are intended to support the publication of opportunity data as open data for anyone to access, use and share. This specification is ideal for those new to publishing open data or those that are not in a position to publish individual dated and timed events or facility slots. The model may be useful in guiding the development of new and existing systems and applications that consume opportunity and organisation or club data.
The specification is an output of the OpenActive Community Group
The data model described in this document has been mapped to existing standards and vocabularies, including SKOS and the Schema.org types and properties.
This specification was published by the OpenActive Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.
Contributions to this document are welcomed. Please add any solutions, comments, or improvements you might have via GitHub.
Lack of access to up to date information about opportunities for sport and physical activity is a barrier to getting people active. The OpenActive initiative, as a community of representatives from across the sector, has developed a range of data specifications to address this, using data to help people get active.
In our ideal user experience, a person can readily search online for opportunities nearby, find enough detail to understand if the activity is appropriate for their particular circumstances, then directly reserve a place in a class or book a court or facility.
Feedback from the sector shows:
This specification aims to support the sharing of open data about clubs and organisations providing opportunities for activity. By improving consistency in the provision of such data, consumers can have more confidence in data supply and data quality and develop innovative methods to engage potential end-users.
The original OpenActive Opportunity data model was centered around Events. This specification is based on the following pattern or profile of elements from that model:
Organization An Organization is a basic entity to represent an organization such as a school, NGO, corporation, club, etc. Relevant organization subclasses here include (but are not limited to):
Activity OpenActive’s primary focus is physical activity - any exercise, sport or other form of bodily movement that involves physical effort. The recommended approach is to use the OpenActive Activity List, based on the SKOS standard for publishing controlled vocabularies.
The Activity List describes a set of Physical Activities. An Activity List may be a simple list of activity names, but it can also capture additional information. Examples include alternative names for an activity e.g. "Soccer" is a synonym for "Football". Further, to group activities, we can define "broader" and "narrower" relationships. For example Judo, Karate and Kendo are all more specific examples of the broader activity of "Martial Arts".
Place This specification uses Place as a general concept to refer to all types of locations, venues and facilities. Recognising that clubs will vary in the number and type of premises they may operate from, the specification allows that this Place can be defined flexibly. Examples here include:
Reflecting the wide variety of tools and platforms in use, and also that the sector is at an early stage in sharing its data more widely, this specification does not prescribe specific data formats or APIs. Club data could be published as JSON, CSV, XML or other formats.
That said, in the examples that follow, we use the JSON-LD format and recommend this approach. JSON-LD offers several advantages, including its widespread use in modem web tools, its readability for both humans and machines, and its compatibility with linked data principles. For more details, see JSON-LD Best Practices.
The JSON-LD approach is ideally suited for clubs with a website or web page.
OpenActive event data, for sessions and facility slots, are published via the Realtime Paged Data Exchange approach (RPDE). Alongside this standalone specification, we are proposing an aligned update to the Opportunity Data specification, expanding the representation of organisation/club in the data model, and providing (optional) guidance for publishing club data via RPDE feeds.
This would support ongoing publication of up-to-date information about affiliated clubs from National Governing Bodies, paving the way for the addition of sessions and slots as a club’s data skills and systems evolve.
Schema.org’s Organization, SportsClub and SportsOrganization types support a common set of properties to describe the information required:
| Key | Property | Status | Format | Notes |
|---|---|---|---|---|
| name | schema:name | REQUIRED | String | The name of the organisation. |
| description | schema:description | Recommended | String | A free text description containing a brief summary of the organisation. |
| url | schema:url | Recommended | String | A URL to the organisation’s website homepage or other page about the organisation.1 |
| sameAs | schema:sameAs | Recommended | String or array of String | Lists the URL(s) of the official social media profile pages associated with the organisation.1 |
| activity | oa:activity | REQUIRED | Array of skos:Concept | Specifies one or more physical activities that are provided by the organisation. |
| location | schema:location | REQUIRED | schema:Place or array of schema:Place, schema: address, String | The main address of the organisation or key locations of the activities provided by the organisation. |
| schema:email | Optional | String | A contact email address for the organisation.1 | |
| telephone | schema:telephone | Optional | String | A contact telephone number for the organisation.1 |
| logo | schema:logo | Optional | schema:ImageObject | A URL to an image associated with the organisation which can be presented alongside its name. |
| alternateName | schema:alternativeName | Optional | String or array of String | Aliases, common acronyms or alternative names for the organisation. |
| genderRestriction | oa:genderRestriction | Optional | oa:GenderRestrictionType | Indicates that an organisation provides activities that are restricted to Male or Female participants, or that there are no restrictions. 3 values are defined as URIs however see related discussion. |
| ageRange | oa:ageRange | Optional | schema:QuantitativeValue | Indicates that an organisation provides activities suitable for a specific age range. Specified as a QuantitativeValue with minValue and maxValue properties |
| memberOf | schema:memberOf | Optional | String | The Organisation Id for an organisation that this club is affiliated to. For example, a club can link to its National Governing Body. |
| member | schema:member | Optional | String or array of String | The organisation IDs for organisations affiliated to this organisation. For example, a National Governing Body can list its current affiliated clubs. |
1 At least one form of contact information (url, sameAs, email, or telephone) MUST be provided for each organisation.
The OpenActive Activity List provides an openly licensed standard activity list that can be used by organisations. It is a controlled vocabulary published using the types and properties defined by the SKOS standard. That standard allows:
If you would like to propose additions or improvements to the list please use this form.
The following properties from the SKOS specification can be used to describe physical activities.
| Key | Property | Status | Format | Notes |
|---|---|---|---|---|
| prefLabel | skos:prefLabel | REQUIRED | String | Preferred label for the physical activity. |
| inScheme | skos:inScheme | Recommended | URI | Link to the Activity List in which this physical activity is defined e.g. “https://openactive.io/activity-list” |
| altLabel | skos:altLabel | Optional | Array of String | Alternative labels for the physical activity |
| broader | skos:broader | Optional | Array of URI | Where an Activity List is organised as a hierarchy of activities, this property can be used to refer to a parent or broader term. E.g. "Martial Arts" is broader than "Tai Chi". |
| narrower | skos:narrower | Optional | Array of URI | Where an Activity List is organised as a hierarchy of activities, this property can be used to refer to a child or narrower term. E.g. "Tai Chi" is a narrower term of "Martial Arts" |
| notation | skos:notation | Optional | String | Provides a unique code or identifier for an activity |
The following table lists a number of properties that can be used to describe a place. This includes a number of optional properties from the full OpenActive opportunity data model.
| Key | Property | Status | Format | Notes |
|---|---|---|---|---|
| name | schema:name | REQUIRED | String | The name of the Place |
| address | schema:address | Recommended | schema:PostalAddress or String | The street address of the location, expressed as a schema:PostalAddress. Where possible publishers should specify an address as an object. |
| geo | schema:geo | Recommended | schema:GeoCoordinates | The geographic co-ordinates, specified as a latitude and longitude of a Place |
| description | schema:description | Optional | String | A free text description of the Place |
| image | schema:image | Optional | Array of schema:ImageObject | One or more images or photos that depicts the Place |
| URI | schema:url | Optional | URI | A URL to a web page (or section of a page) that describes the Place |
| identifier | schema:identifier | Optional | Number, String, schema:PropertyValue | A local identifier for the resource. |
| containInPlace | schema:containedInPlace | Optional | schema:Place | Indicates that this Place is part of a larger location. Can be used to allow, e.g. a pitch or other facility to be related to a parent location such as a Leisure Centre |
| containsPlace | schema:containsPlace | Optional | Array of schema:Place | Relates a Place to one or more other locations and facilities that it contains. |
| telephone | schema:telephone | Optional | String | A contact telephone number for the location, e.g. for enquiries |
| openingHoursSpecification | schema:openingHoursSpecification | Optional | Array of schema:OpeningHoursSpecification | Specifies the opening hours of a location. |
| amenityFeature | schema:amenityFeature | Optional | Array of schema:LocationFeatureSpecification | Used to indicate whether specific amenities are available at a location, through an array of schema:LocationFeatureSpecification objects. |
Schema.org provides the following properties for publishing address data using the schema:PostalAddress type.
| Key | Property | Status | Format | Notes |
|---|---|---|---|---|
| streetAddress | schema:streetAddress | REQUIRED | String | Street address |
| addressLocality | schema:addressLocality | REQUIRED | String | Town or other area |
| addressRegion | schema:addressRegion | REQUIRED | String | Region |
| postalCode | schema:postalCode | REQUIRED | String | Postcode |
| addressCountry | schema:addressCountry | REQUIRED | String | ISO 3166-1 alpha-2 country code |
A more precise geographical location can be provided for a schema:Place by adding a schema:geo property. The value of this property is a schema:GeoCoordinates object, with the following properties.
| Key | Property | Status | Format | Notes |
|---|---|---|---|---|
| latitude | schema:latitude | REQUIRED | Number | Latitude |
| longitude | schema:longitude | REQUIRED | Number | Longitude |
Latitude and longitude values should be provided to a precision of at least two decimal places in order to be useful to consumers.
To illustrate the basic concepts and the JSON-LD representation, consider the following examples, adapted from an existing OpenActive opportunity based at a club.
Example 1: Starting with the simplest example, using required fields only, in their simplest form. (This is for illustrative purposes only and not recommended at all.)
“@context”, “@type” and “@id” are JSON-LD keywords.
The following script could be added at the end of the 'head' tag on the club’s website.
<script type="application/ld+json">
{
"@context": "https://openactive.io/",
"@type": "Organization",
"@id": "https://opensessions.io/api/id/organizers/2572",
"name": "Greenwich Yacht Club",
"activity": [
{
"@type": "Concept",
"prefLabel": "Rowing"
}
],
"location": "Greenwich Yacht Club, London SE10 0BW, UK"
}
</script>However, using the fuller specification allows us to provide much richer information. As this is done consistently between data publishers, data consumers can collate the information more easily.
Example 2: Using the REQUIRED and Recommended fields, in their recommended forms
<script type="application/ld+json">
{
"@context": "https://openactive.io/",
"@type": "Organization",
"@id": "https://opensessions.io/api/id/organizers/2572",
"name": "Greenwich Yacht Club",
"description": "Community amateur sports club focused on getting people sailing.",
"url": "http://www.greenwichyachtclub.co.uk",
"sameAs": [
"http://www.greenwichyachtclub.co.uk",
"https://www.facebook.com/GreenwichYachtClub/",
"https://www.twitter.com/greenwichYC"
],
"activity": [
{
"@id": "https://openactive.io/activity-list\#d2733a1c-662c-427a-a270-400171c07320",
"@type": "Concept",
"inScheme": "https://openactive.io/activity-list",
"prefLabel": "Rowing"
}
],
"location": {
"@type": "Place",
"name": "Greenwich Yacht Club, London SE10 0BW, UK",
"geo": {
"@type": "GeoCoordinates",
"latitude": 51.4955,
"longitude": 0.018473
},
"address": {
"@type": "PostalAddress",
"streetAddress": "Greenwich Yacht Club, Peartree Wharf, 1 Peartree Way",
"addressLocality": "Greenwich",
"addressRegion": "London",
"postalCode": "SE10 0BW",
"addressCountry": "UK"
},
}
</script>Example 3: Including some of the optional fields to maximise value
The kinds of information included here were identified as valuable by data users in the community.
<script type="application/ld+json">
{
"@context": "https://openactive.io/",
"@type": "Organization",
"@id": "https://opensessions.io/api/id/organizers/2572",
"name": "Greenwich Yacht Club",
"description": "Community amateur sports club focused on getting people sailing.",
"url": "http://www.greenwichyachtclub.co.uk",
"sameAs": [
"http://www.greenwichyachtclub.co.uk",
"https://www.facebook.com/GreenwichYachtClub/",
"https://www.twitter.com/greenwichYC"
],
"email": "training@greenwichyachtclub.co.uk",
"telephone": "02083960321",
"alternateName": [
"GYC"
],
"memberOf": "Royal Yachting Association",
"activity": [
{
"@id": "https://openactive.io/activity-list\#d2733a1c-662c-427a-a270-400171c07320",
"@type": "Concept",
"inScheme": "https://openactive.io/activity-list",
"prefLabel": "Rowing"
}
],
"location": {
"@type": "Place",
"name": "Greenwich Yacht Club, London SE10 0BW, UK",
"geo": {
"@type": "GeoCoordinates",
"latitude": 51.4955,
"longitude": 0.018473
},
"address": {
"@type": "PostalAddress",
"streetAddress": "Greenwich Yacht Club, Peartree Wharf, 1 Peartree Way",
"addressLocality": "Greenwich",
"addressRegion": "London",
"postalCode": "SE10 0BW",
"addressCountry": "UK"
},
"amenityFeature": [
{
"name": "Changing Facilities",
"@type": "ChangingFacilities",
"value": true
},
{
"name": "Showers",
"@type": "Showers",
"value": true
},
{
"name": "Toilets",
"@type": "Toilets",
"value": true
},
{
"name": "Parking",
"@type": "Parking",
"value": true
},
{
"name": "Lockers",
"@type": "Lockers",
"value": false
},
{
"name": "Towels",
"@type": "Towels",
"value": false
},
{
"name": "Creche",
"@type": "Creche",
"value": false
},
{
"name": "Baby Changing",
"@type": "BabyChanging",
"value": false
}
]
},
}
</script>For examples illustrating how to use this specification with club or league management systems, and via real-time paged data exchange (RPDE), look out for forthcoming updates to the OpenActive opportunity specification.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MUST and REQUIRED in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.