This document is also available in this non-normative format: diff to previous version
Copyright © 2017 the Contributors to the Modelling Opportunity Data 1.0 Specification, published by the OpenActive Community Group under the W3C Community Final Specification Agreement (FSA). A human-readable summary is available.
This specification introduces a data model to support the publication of data describing opportunities for people to engage in physical activities ("opportunity data"). This model covers description of activities, as well as the events and locations in which they take place.
The specification is intended to support the publication of opportunity data as open data for anyone to access, use and share. It will also guide reusers of opportunity data, introducing them to the key concepts relevant to that sector.
The model may also be useful in guiding the development of both new and existing booking systems and applications that consume opportunity data.
The specification is an output of the OpenActive Community Group and serves as a common reference point for other specifications and outputs of that activity.
Developers looking for a quick primer on the model and how to use it to structure opportunity data may want to refer to the [Publishing-Opportunity-Data] primer which provides a number of additional examples.
The data model introduced in this document has been mapped to existing standards and vocabularies, including SKOS ([SKOS]) and the Schema.org ([SCHEMA-ORG]) types and properties. This existing work provides a useful existing framework around which the OpenActive Community Group can build additional data standards.
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 Final Specification Agreement (FSA) other conditions apply. Learn more about W3C Community and Business Groups.
Contributions to this document are not only welcomed but are actively solicited and should be made via GitHub Issues and pull requests. The source code is available on GitHub.
If you wish to make comments regarding this document, please send them to public-openactive@w3.org (subscribe, archives).
This section is non-normative.
The W3C OpenActive Community Group was established with the objective of facilitating the sharing and use of physical activity data. Open publishing of this data has enormous potential to increase participation in physical activities.
There are several different categories of data that are relevant to physical activities. This data covers different parts of the data spectrum and is represented in the following diagram.
Some of this data is shared data. It can only be accessed by specific people or groups, under terms and conditions that define how and when it can be accessed and used. This shared data includes personal data about people taking part in activities and participation data that describes how people have been involved in previous events.
Some of this data can be open data. Open data is data that anyone can access, use and share. All of the following types of data can be published as open data:
Collectively this is known as opportunity data.
This specification has been developed to meet a broad set of requirements.
As described in the previous section, opportunity data covers a variety of different types of information including data on venues, activities and events. The specification should support publication of all of these different types of data
The aim of the OpenActive initiative is to encourage people to be more physically active. This means that this specification should focus on the data that will help people discover these opportunities.
The specification should be inclusive and support sharing of opportunity data about all types of physical activities, not just sports.
At present the physical activity sector does not have a standard list of physical activities. The specification should allow data providers to share the lists they have and support the sector in moving towards a standardised list of physical activities
Opportunity data is collected and held in a variety of different tools, platforms and websites. There is variation in the amount of detail held about individual events so the specification must provide flexibility to share what data is currently available, whilst guiding activity providers towards additional useful data to collect about events.
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 should not prescribe specific data formats or APIs. Ideally opportunity data could be published as JSON, XML, CSV or other formats.
This specification should support extensions to allow it to be customised and revised to meet future requirements, as well as the needs of specific communities of data publishers and consumers.
This specification defines a data model for opportunity data. This reflects the goal of the OpenActive initiative whose aim is to encourage the publishing and reuse of open data that might help people to become more active.
The following items are therefore out of scope for this specification:
The OpenActive Community Group may produce additional specifications that address these areas.
This specification is divided into two main sections:
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 MAY, MUST, OPTIONAL, RECOMMENDED, REQUIRED, and SHOULD are to be interpreted as described in [RFC2119].
This specification makes use of the compact IRI Syntax; please refer to the Compact IRIs from [JSON-LD].
The following typographic conventions are used in this specification:
markup
Notes are in light green boxes with a green left border and with a "Note" header in green. Notes are normative or informative depending on the whether they are in a normative or informative section, respectively.
Examples are in light khaki boxes, with khaki left border, and with a
numbered "Example" header in khaki. Examples are always informative.
The content of the example is in monospace font and may be syntax colored.
This section introduces the high-level data model for opportunity data. This includes a description of the:
The model also helps to provide definitions of key terms that are used throughout this specification.
This diagram illustrates the resources and relationships that are introduced in the following sections.
A Physical Activity is an exercise, sport or other form of bodily movement that involves physical effort. Physical activities will usually have a well-understood, dictionary definition.
Examples of Physical Activities include walking, running, cycling, rugby, football and tennis
Activities should have a name. They might also be associated with one of more synonyms that provide alternative names for that activity. E.g. "Soccer" is a synonym for "Football". This additional information may be useful to help improve search engines and improve data collection.
Physical Activities may also have additional information associated with them. For example a sporting activity might be overseen by a governing body or federation.
Physical Activities might also be recognised by different bodies. In the UK certain activities are recognised as suitable for educational assessments, while others may be recognised by funding bodies like Sport England.
An Activity List describes a set of Physical Activities. An Activity List may be a simple list of activity names. But an Activity List might also capture additional information. A common requirement is to describe relationships between Physical Activities.
One method of grouping activities is to define "broader" and "narrower" relationships. For example Judo, Karate and Kendo are all more specific examples of the broader activity of "Martial Arts".
This type of grouping could also be used to describe the disciplines associated with Physical Activities. For example olympic and open water swimming.
An Activity List might also group Physical Activities into collections. For example swimming, water aerobics, and water polo might all be classified as "Water Sports". Water polo and football might also be grouped into a collection of "Team Sports".
An Activity List may include any number of collections of Physical Activities. As shown in the example above, an individual Physical Activity might be present in more than one grouping.
Some systems may choose to use grouping and hierarchical relationships between Physical Activities to help people find opportunities to be active. For example a search engine might offer users results for all types of Martial Art, or for Karate specifically.
The proposed model for Activity Lists is based on the [SKOS] standard for publishing controlled vocabularies.
It is not a requirement that systems store, publish or use relationships between Physical Activities. A system may choose to treat Physical Activities as simple tags or categories associated with Events. Other systems may define a fixed list of Physical Activities that are used as a controlled vocabulary to guides user input and data collection. Others may adopt a more complex hierarchical approach.
Developing a standard activity list
This specification doesn't place any requirements on how applications manage or use Physical Activities or Activity Lists. There is no requirement that applications that implement this specification must adopt a single standardised list, or agree on standard groupings. The intention here is to just capture a useful model that can represent the variety of data currently in use.
However there are benefits to the physical activity sector in convergence on a standard list of activities in order to improve discovery, reporting, etc. The OpenActive Community Group are developing a standard list as a separate activity. For more information see [OpenActive-Activity-List].
An Event is an opportunity to take part in a Physical Activity. Events take place at a specific location (see below) at an agreed date and time.
Some Events are one-off occurrences. For example a fun run organised by a local group may run as a standalone event on a particular date.
Other events take place on a regular schedule. For example a weekly gym class may run every Wednesday evening at 7pm. While a local walking club might meet on a Saturday morning once a month.
In order to simplify terminology we recommend the use of the term "Event" to refer to both individual occurrences and regularly occurring events.
It is useful to publish data about both individual Events and those with recurring schedules. People looking for opportunities to be active will be interested in both specific questions ("what can I do tomorrow") and more general information about scheduled activities.
Regardless of whether an event takes place only once or happens on a regular schedule, there is a range of additional information that may help describe the event to potential participants. This includes:
There are a variety of ways to categorise and describe events. This includes restrictions on attendance, aspect of suitability for different audiences and fitness levels, and a mixture of pre-requisites such as the need for certain qualifications, membership or equipment.
The initial version of this specification prioritises capturing the essential elements of describing an event. The structured information about time, place and activity is supplemented with some basic descriptive properties. This also includes the ability to add "tags" to an event to capture a variety of categorisation elements. Future versions of this specification will use experience working with real-world data to decide the best approach of formalising these categories.
Events have organisers. An event organiser might be a Person or an Organization. The organiser of an event is the person or organisation who arranged and/or hosts the event. The organizer will be the person or organisation who is ultimately responsible for an Event.
Examples of organisers might be coaches, or a local sports club.
Events may involve other named individuals or organisations. Examples might include named staff who will be participating in the event in addition to the main organiser. These are referred to as contributors.
In addition to their names, some systems may have additional information about organisers and contributors. E.g. links to their web sites, photos, logos or contact details.
Applications must not publish personal data without permission
This specification provides a data model for publishing information about individual people, e.g. coaches, volunteers, etc. However applications MUST respect privacy and data protection laws and must not publish data about individuals without their consent.
The ability to publish this type of data has been included because event organisers often choose to publicly share some information about themselves to help advertise an event. E.g. their name and some background on their qualifications or experience. But this information MUST not be published as open data without getting the consent of the individual concerned.
Events take place in a location. But, depending on the activity, the location may be defined to different levels of precision. For example:
In addition to this, data publishers will have different approaches for capturing location data.
Recognising this need for flexibility, this model proposes that a location can be specified as any of the following:
This specification uses Place as a general concept to refer to all types of locations, venues and facilities.
The concept of Place therefore covers general outdoor areas such as parks, event venues (e.g. a Leisure centre) and facilities within a venue (e.g. a squash court, running track, etc). Facilities are contained in Places.
Places may have additional descriptive properties, for example:
To help distinguish between equipment and facilities: facilities will be fixed features of a location, e.g. squash courts or a walking trail; equipment will be items like table tennis tables that may be moved around a facility.
Events are often organised and run in a variety of different ways. This tailoring might include adjusting the activity to a particular type of participant, demographic. Or it could include running the event in a particular style, e.g. with a fixed routine or sequence of activities.
A Programme describes a method of carrying out a Physical Activity. Some programmes are very loosely defined. While others are more structured and may be run to a specific agenda or in a particular style.
Programmes are often associated with branding or marketing that helps participants understand more about what they can expect from an event of that format. Formats might be offered or overseen by specific organisations
Examples of programmes include:
Programmes provide another means of tagging or describing Events to help describe them to participants. When participants are looking for opportunities they may be interested in discovering Events based on either the general activity (e.g. Running) or a specific programme (Back to Netball).
Not all opportunities to be physically active are organised Events. Some opportunities are self-directed for example:
The common elements here are that facilities are provided for use at a time of the participants choosing (within limits of opening hours or availability), rather than at a time or schedule specified by the organiser.
However many of the other aspects of describing an Event are applicable to describing this type of opportunity. For example:
In this specification this type of self-guided activities will be referred to as Activity Opportunities.
Some opportunities are freely available for anyone to attend. Others are only available to members or paying attendees.
An Offer is used to describe the terms under which a participant can pay to attend an event.
The concept of an Offer is taken from Schema.org, which itself references the Good Relations vocabulary for ecommerce. The data model described in a later section is not intended as a complete specification. The concept is introduced in this version of specification to highlight the support available in Schema.org for associating offers with events. Later versions of the specification will explore the area of booking in more detail.
The data model described in the following sections reuses existing standards and vocabularies which have then been extended to cover the additional requirements needs to support the publication of opportunity data.
The Simple Knowledge Organisation System ([SKOS]) is a W3C standard for publishing taxonomies and category schemes. It can be used to help publish and organise Activity Lists and to describe Physical Activities.
Schema.org [SCHEMA-ORG] provides an existing well-used and documented data model for publishing data to the web. It provides an existing model for describing Events, Organisations, People, and Places.
Both standards are widely used, and can be used to publish data in a variety of structured formats, including [JSON-LD].
The OpenActive Vocabulary [OpenActive-Vocabulary] is a custom vocabulary designed to support the publication of opportunity data. It defines a number of new terms that extend SKOS and Schema.org to cover additional requirements highlighted in this specification.
Developers looking for a quick primer on the model and how to use it to structure opportunity data may want to refer to the [Publishing-Opportunity-Data] primer which provides many more examples.
The rest of this specification make use of the following namespaces:
dc:
http://purl.org/dc/terms/
schema:
http://schema.org/
skos:
http://www.w3.org/2004/02/skos/core#
oa:
https://www.openactive.io/ns/
In the following sections all referenced terms have been qualified using their namespace prefix. This highlights the source vocabulary in which they have been defined. Terms have also been linked to their definitions.
The examples in each section use [JSON-LD] syntax and reference the OpenActive JSON-LD context defined by [OpenActive-Vocabulary].
The context removes the need to use explicit namespace prefixes in the JSON documents. The context also maps the JSON-LD @type
and @id
properties to simple keys (type
and id
). This further limits the amount of JSON-LD syntax exposed to developers.
The following table provides a high-level summary of how the concepts introduced in the previous sections map to definitions in SKOS, Schema.org and the OpenActive Vocabulary ([OpenActive-Vocabulary]).
Concept | Mapping | Notes |
---|---|---|
Activity List | skos:ConceptScheme |
Activity lists are controlled vocabularies and map well to the definition of a SKOS Concept Scheme. |
Physical Activity | skos:Concept |
Individual Physical Activities can be represented as individual SKOS concepts |
Event | schema:Event |
Schema.org provides a well defined model for Events already with properties that cover many of the core requirements for opportunity data |
Place | schema:Place |
As well as the general definition of a Place, Schema.org defines sub-types including
schema:EventVenue and schema:SportsActivityLocation which can be used where appropriate |
Organization | schema:Organization |
Covers all types of organisations, including companies, clubs, etc |
Person | schema:Person |
An individual person |
Programme | skos:Concept |
|
Activity Opportunity | oa:ActivityOpportunity |
An opportunity to carry out an activity at a location, at a time of the participants choosing. |
Offer | schema:Offer |
Schema.org provides an existing model for describing offers to pay to participate in an Event. |
This specification adopts the same approach as Schema.org and encourages the use of URLs as unique identifiers for resources.
Information about Events, Places, Organizations and other types of resources should already have been published online to make that information accessible to users. Using existing URLs as identifiers avoids the need to define a new identifier scheme for resources described in opportunity data.
There will generally be a single canonical URL for a resource, e.g. the homepage for an Organization or Place, or a public web page advertising an Event.
If there are several different URLs that may be used to identify a resource, it is recommended that systems use:
This specification provides three properties for identifying resources:
@id
- is used to assign a globally unique URI to a resource. This may resolve to further machine-readable information about the resource. When supplied, this URI
MUST be stable and unchanging over time. Applications harvesting and indexing opportunity data SHOULD use
this as the unique identifier for the resource
schema:url
- provides a link to a public web page about the resource. Further machine-readable metadata
MAY be discoverable from that web page. Applications MUST be able to use this URL as a means for providing
users with a link to more information about a resource
schema:identifier
- provides a means of sharing non-URI identifiers for a resource, e.g. a company or registration number for an Organization, or an internal identifier for an Event.
Applications MAY use this as a unique identifier for the resource, if there is no @id
available.
In short, the @id
property provides a unique global identifier, while the schema:url
provides a means to provide a link to a public web page about a resource.
If applicable then publishers may choose to use the same URI for these two properties. If an @id
property is not provided then applications MAY choose to rely on the
value of this property as a unique identifier.
The option to use two different URLs is useful when there is a need to distinguish between a unique identifier and a public resource. For example a platform hosting opportunity data may need to assign a unique identifier to a resource that is separate to its public web page.
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"id": "http://host.opportunity-data.com/id/12345",
"url": "http://my-leisure-centre.example.org/events/1",
"name": "Tai chi Class"
}
In the above example the @id
property provides a unique identifier across the hosting application. But the public URL for the Event uses a separate, customer-specific domain.
The following sections include more detail about the properties available to describe each type of resource. Some properties are considered to be essential to ensure the provision of a minimally useful set of information about each resource. These REQUIRED properties must be provided.
All other properties are considered to be optional but it is RECOMMENDED that they be provided where possible.
Data publishers MAY include additional properties, e.g. from Schema.org or other vocabularies when helpful to describe their data. See the section on Extending the Model for more information.
Applications that consume opportunity data MUST ignore any properties that they don't understand. This allows data publishing practices within the sector to evolve as required.
schema:Event
)The Schema.org schema:Event
type corresponds to the definition of Event given earlier in this specification. The properties and relationships associated with the
schema:Event
type can all be used to describe events.
The following table illustrates how the essential aspects of describing an event map to existing Schema.org properties and/or properties defined in the OpenActive Vocabulary.
Property | Status | Notes |
---|---|---|
@id |
REQUIRED | A URI providing a unique identifier for the resource |
schema:url |
REQUIRED | A URL to a web page (or section of a page) that describes the event |
schema:identifier |
OPTIONAL | A local identifier for the resource |
schema:name |
REQUIRED | The name of the event |
schema:description |
RECOMMENDED | A free text description of the event |
schema:image |
OPTIONAL | An image or photo that depicts the event, e.g. a photo taken at a previous event |
schema:startDate |
OPTIONAL |
The start date and time of the event. Can be specified as a While this property is marked as OPTIONAL, a data publisher MUST provide either a |
schema:endDate |
OPTIONAL |
The end date and time of the event. Can be specified as a
It is RECOMMENDED that publishers provide either an |
schema:duration |
RECOMMENDED | The duration of the event given in [ISO8601] format. |
schema:location |
REQUIRED | The location at which the event will take place. Or, in the case of events that may span multiple locations, the initial meeting or starting point.
It is recommended that locations SHOULD be specified as a If only an address is available then this SHOULD be described as a
Applications MAY use |
schema:organizer |
RECOMMENDED | The person or organization ultimately responsible for an event. An organizer might be an schema:Organization or a schema:Person . |
schema:contributor |
RECOMMENDED | A schema:Person , e.g. a coach, staff member or volunteer who will be helping to run the event. |
schema:maximumAttendeeCapacity |
OPTIONAL | The maximum capacity of the event |
schema:remainingAttendeeCapacity |
OPTIONAL | The number of places that are still available for the event |
schema:eventStatus |
RECOMMENDED | The status of an event. Can be used to indicate rescheduled or cancelled events |
schema:subEvent |
OPTIONAL | Relates a parent event to a child event. Properties describing the parent event can be assumed to apply to the child, unless otherwise specified. A child event might be a specific instance of an Event within a schedule |
schema:superEvent |
OPTIONAL | Relates a child event to a parent event. Properties describing the parent event can be assumed to apply to the child, unless otherwise specified. A parent event might specify a recurring schedule, of which the child event is one specific instance |
schema:schedule |
OPTIONAL | A schedule defines a repeating time period used to describe a regularly occurring Event. **Note: this is a draft Schema.org property. See Issue) for discussion. |
oa:activity |
REQUIRED | Specifies the physical activity or activities that will take place during an event |
oa:category |
RECOMMENDED | Provides a set of tags that help categorise and describe an event, e.g. its intensity, purpose, etc. |
oa:ageRange |
OPTIONAL | Indicates that an event is suitable for a specific age range. If only a single age is specified then this is assumed to be a minimum age. Age ranges can be specified as follows: 18-30 |
oa:genderRestriction |
OPTIONAL | Indicates that an event is restricted to male, female or a mixed audience. If a gender restriction isn't specified then applications SHOULD assume that an event is suitable for a mixed audience |
oa:programme |
OPTIONAL | Indicates that an event will be organised according to a specific Programme |
oa:attendeeInstructions |
OPTIONAL | Provides additional notes and instructions for event attendees. E.g. more information on how to find the event, what to bring, etc. |
oa:leader |
OPTIONAL | Refers to a person (schema:Person ) who will be leading an event. E.g. a coach. This is a more specific role than an organiser or a contributor |
oa:accessibilitySupport |
OPTIONAL | Used to specify the types of disabilities or impairments that are supported at an event |
oa:accessibilityInformation |
OPTIONAL | Provide additional, specific documentation for participants about how disabilities are, or can be supported at the Event. |
oa:isCoached |
OPTIONAL | A boolean property that indicates whether an Event will be coached. This flag allows an Event to be marked as being coached without having to specify a named individual as a coach. This addresses both privacy concerns and also scenarios where the actual coach may only be decided on the day. |
oa:level |
OPTIONAL | A general purpose property for specifying the suitability of an event for different participant “levels”. E.g. beginner/intermediate/advanced. Or in the case of martial arts, specific belt requirements. Values SHOULD ideally be drawn from a controlled vocabulary. |
oa:meetingPoint |
OPTIONAL | Instructions for the attendees of an Event about where they should meet the organizer or leader at the start of the event. Some larger locations may have several possible meeting points, so this property provides additional more specific directions. |
The following example shows a simple event description, including its start time and duration:
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Tai chi Class",
"description": "A tai chi class intended for beginners",
"attendeeInstructions": "Please wear trainers and comfortable clothing",
"startDate": "2017-03-22T20:00:00-05:00",
"duration": "PT60M"
}
This basic description can be improved by providing information about its location and organizer.
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Tai chi Class",
"description": "A tai chi class intended for beginners",
"attendeeInstructions": "Please wear trainers and comfortable clothing",
"startDate": "2017-03-22T20:00:00-05:00",
"duration": "PT60M",
"organizer": {
"type": "Organization",
"url": "http://example.org/orgs/bristol-tai-chi",
"name": "Bristol Tai Chi" },
"location": {
"type": "Place",
"name": "ExampleCo Gym",
"address": {
"type": "PostalAddress",
"streetAddress": "1 High Street",
"addressLocality": "Bristol",
"postalCode": "BS1 4SD"
}
}}
The oa:activity
property allows an event to be associated with one or more Physical Activities. Its simplest usage is as follows:
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Tai chi Class",
"description": "A tai chi class intended for beginners",
"startDate": "2017-03-22T20:00:00-05:00",
"duration": "PT60M",
"oa:activity": "Tai chi"
}
This specifies that the event will involve Tai Chi. Multiple activities can be specified by using repeated values:
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Tai chi Class",
"description": "A tai chi class intended for beginners",
"startDate": "2017-03-22T20:00:00-05:00",
"duration": "PT60M",
"activity": ["Tai chi", "Martial Arts", "Combat"]
}
The Physical Activities used to describe an event may be drawn from a standard Activity List, e.g. the OpenActive Activity List ([OpenActive-Activity-List]).
In this case it is useful to make this clear in the opportunity data. In the following example the Physical Activity associated with the Event is shown as a structured value. This allows more information to be provided, including its identifier, its label and a reference to the identifier of the Activity List from which it has been drawn:
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Tai chi Class",
"description": "A tai chi class intended for beginners",
"startDate": "2017-03-22T20:00:00-05:00",
"duration": "PT60M",
"activity": {
"id": "https://www.openactive.io/activity-list/#c16df6ed-a4a0-4275-a8c3-1c8cff56856f",
"type": "Concept",
"prefLabel": "Tai Chi",
"inScheme": "https://www.openactive.io/activity-list/"
}
}
Applications could include additional information, e.g. alternate labels for convenience of consumers.
And, as shown in the earlier example, multiple activities can be specified by specifying an array of objects.
The oa:category
property can be used to associate an Event with one or more tags that provide some extra context about an event. This might include general information on
the intensity and suitability. While this property can be used to add any arbitrary tags to an Event, a common use case is the need to tag an event as being suitable for a specific type of audience, e.g. Beginners. Where this information
is available, the oa:level
property can be used in preference to oa:category
.
If an application does not distinguish between different types of tags associated with an Event, then it SHOULD use the more general oa:category
property.
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Tai chi Class",
"description": "A tai chi class intended for beginners",
"startDate": "2017-03-22T20:00:00-05:00",
"duration": "PT60M",
"category": ["Suitable for all", "Low intensity"],
"level": ["Beginner"]
}
Applications publish data using the oa:category
and oa:level
properties MAY
use values either from a controlled vocabulary or more free-form user entered labels.
Where an application is using a controlled vocabulary it SHOULD publish that vocabulary as structured data.
In future, the OpenActive Community Group may decide to define and recommend some controlled vocabularies for use in these properties. At present the values of these properties are left deliberately open to encourage publication of open data that may inform future standardisation.
There are a variety of ways in which the suitability of an event for specific audiences can be expressed. This includes specifying that an event is:
The following example illustrates how to indicate that an event it targeted as a specific age range (over 60s) but is open to a mixed audience:
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Tai chi Class",
"description": "A tai chi class intended for beginners",
"startDate": "2017-03-22T20:00:00-05:00",
"duration": "PT60M",
"ageRange": 60,
"genderRestriction": "mixed"
}
Events can be associated with a Programme using the oa:programme
property. In its simplest form this allows the name of a Programme to be associated with an event:
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Rowing Class",
"description": "A rowing class for beginners",
"startDate": "2017-04-01T08:00:00",
"duration": "PT60M",
"level": ["Beginner"],
"programme": "Learn to Row"
}
If more information about the programme is available, then this can be included by describing the Programme in a more structured way:
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Rowing Class",
"description": "A rowing class for beginners",
"startDate": "2017-04-01T08:00:00",
"duration": "PT60M",
"level": ["Beginner"],
"programme": {
"name": "Learn to Row",
"url": "https://www.britishrowing.org/go-rowing/learn-to-row/",
"description": "Getting started in rowing couldn’t be easier!"
}
}
Schema.org support for recurring events
Issue 2: Schema.org support for recurring events
This specification relies on some pending changes to Schema.org that will add recurrence rules to Events. The proposal has been accepted, but is not yet formally part of the model.
We expect that this proposal will become part of Schema.org in due course. This process will be driven by implementation experience and feedback from the community. On that basis we have included the terms in specification. The following section is written on that basis. However both publishers and consumers should be aware that this is an area that may change in future versions.
The following example illustrates basic usage of the schema:eventSchedule
property. The data describes a Tai Chi class that occurs every
Weds at 7pm
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Tai chi Class",
"description": "A tai chi class intended for beginners",
"duration": "PT60M",
"eventSchedule": {
"type": "Schedule",
"startDate": "2017-01-01",
"endDate": "2017-12-31",
"frequency": "weekly",
"byDay": "http://schema.org/Wednesday",
"startTime": "19:00",
"endTime": "20:00"
}}
Schema.org provides a couple of basic properties for describing the maximum (schema:maximumAttendeeCapacity
) and remaining capacity (schema:remainingAttendeeCapacity
)
for an schema:Event
.
These properties can be used to provide some basic availability information for scheduled events. These are illustrated in the following example which states that a Tai chi class can be attended by up to 20 people and that there are 4 spaces remaining.
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Tai chi Class",
"description": "A tai chi class intended for beginners",
"startDate": "2017-03-22T20:00:00-05:00",
"duration": "PT60M",
"maximumAttendeeCapacity": 20,
"remainingAttendeeCapacity": 4
}
An schema:Event
may occasionally be rescheduled or cancelled. Schema.org provides the schema:eventStatus
property for indicating
the current status of an event.
The property can have several standardised values which are defined by the schema:EventStatusType
enumeration. The property values should therefore be one of the following URIs:
http://schema.org/EventCancelled
http://schema.org/EventPostponed
http://schema.org/EventRescheduled
http://schema.org/EventScheduled
If the status property is not provided then applications SHOULD assume a default value of http://schema.org/EventScheduled
.
The following example shows a Tai chi class that has been cancelled:
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Tai chi Class",
"description": "A tai chi class intended for beginners",
"startDate": "2017-03-22T20:00:00-05:00",
"duration": "PT60M",
"eventStatus": "http://schema.org/EventCancelled"
}
This specification defines several ways to capture information from organisers about the types of support they provide for people with disabilities or other impairments. This includes:
oa:accessibilitySupport
propertyoa:accessibilityInformation
propertyExamples of using these are shown below:
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Tai chi Class",
"description": "A tai chi class intended for beginners",
"startDate": "2017-03-22T20:00:00-05:00",
"duration": "PT60M",
"accessibilitySupport": ["Hearing Impairment", "Visual Impairment"],
"accessibilityInformation": "The location is fully accessible, please contact the organiser if you have questions"
}
schema:Place
and schema:PostalAddress
)Schema.org takes a flexible approach towards defining the locations for an schema:Event
.
The legal values for the schema:location
property include:
schema:PostalAddress
schema:Place
or one of its sub-types such as a schema:CivicStructure
or schema:EventVenue
While all three forms are allowed by Schema.org, applications that publish opportunity data SHOULD either specify a schema:PostalAddress
or a more detailed schema:Place
description.
Schema.org provides the following properties for publishing address data using the schema:PostalAddress
type.
Property | Status | Notes |
---|---|---|
schema:streetAddress |
REQUIRED | Street address |
schema:addressLocality |
REQUIRED | Town or other area |
schema:region |
REQUIRED | Region |
schema:postalCode |
REQUIRED | Postcode |
The following example shows how to markup a simple address:
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "PostalAddress",
"streetAddress": "North Parade Road",
"addressLocality": "Bath",
"region": "Somerset",
"postalCode": "BA2 4ET"
}
In order to provide additional information, e.g. the name of the location or its geographic co-ordinates, then the schema:Place
type MUST
be used instead.
The following table lists the properties that can be used to provide descriptions of a schema:Place
Property | Status | Notes |
---|---|---|
@id |
REQUIRED | A URI providing a unique identifier for the resource |
schema:identifier |
OPTIONAL | A local identifier for the resource |
schema:url |
REQUIRED | A URL to a web page (or section of a page) that describes the Place |
schema:name |
REQUIRED | The name of the Place |
schema:description |
RECOMMENDED | A free text description of the Place |
schema:image |
OPTIONAL | An image or photo that depicts the place |
schema:address |
RECOMMENDED | The street address of the location, expressed as a schema:PostalAddress . See the following section for more information on describing schema:PostalAddress resources |
schema:geo |
RECOMMENDED | The geographic co-ordinates, specified as a latitude and longitude of a Place |
schema:containedInPlace |
OPTIONAL | 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 |
schema:containsPlace |
OPTIONAL | Relates a Place to other locations and facilities that it contains. Schema.org provides a specific type of Place, called a
schema:SportsActivityLocation for describing facilities |
schema:telephone |
OPTIONAL | A contact telephone number for the location, e.g. for enquiries |
schema:openingHoursSpecification |
OPTIONAL | Specifies the opening hours of a location. The value of this property is a schema:OpeningHoursSpecification . |
This example illustrates a simple place description. Building on the previous example it adds the name, telephone number and website address for the leisure centre:
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Place",
"url": "http://www.better.org.uk/leisure-centre/banes/bath-sports-and-leisure-centre",
"name": "Bath Sports and Leisure Centre",
"address": {
"type": "PostalAddress",
"streetAddress": "North Parade Road",
"addressLocality": "Bath",
"region": "Somerset",
"postalCode": "BA2 4ET"
},
"telephone": "+44 (0)1225 486905"}
A more precise geographical location can be provided by adding a schema:geo
property:
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Place",
"url": "http://www.better.org.uk/leisure-centre/banes/bath-sports-and-leisure-centre",
"name": "Bath Sports and Leisure Centre",
"address": {
"type": "PostalAddress",
"streetAddress": "North Parade Road",
"addressLocality": "Bath",
"region": "Somerset",
"postalCode": "BA2 4ET"
},
"telephone": "+44 (0)1225 486905",
"geo": {
"type": "GeoCoordinates",
"latitude": "51.3816123",
"longitude": "-2.3544367"
}
}
Facilities available at a location can be expressed using the containment properties (schema:containedInPlace
and schema:containsPlace
).
The following example illustrates how to describe that a Leisure Centre includes a gym:
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Place",
"url": "http://www.better.org.uk/leisure-centre/banes/bath-sports-and-leisure-centre",
"name": "Bath Sports and Leisure Centre",
"address": {
"type": "PostalAddress",
"streetAddress": "North Parade Road",
"addressLocality": "Bath",
"region": "Somerset",
"postalCode": "BA2 4ET"
},
"containsPlace": {
"type": "SportsActivityLocation",
"url": "http://www.better.org.uk/leisure-centre/banes/bath-sports-and-leisure-centre/gym",
"name": "Gym"
}}
schema:Person
and schema:Organization
)Applications must not publish personal data without permission
While the schema:Person
type allows a variety of information to be published about a person, applications MUST
not publish this information as open data without consent.
To describe the people and organisations involving in organising Events, Schema.org provides the schema:Person
and schema:Organization
types.
People and organisations can be associated with an Event using the schema:organizer
, schema:contributor
or oa:leader
properties. These allow some flexibility in defining how a person or organisation is associated with an event. For example an event may be:
schema:organizer
)oa:leader
)
oa:contributor
)To help ensure that publishers apply these properties in consistent ways, it is recommended that:
schema:Organization
)oa:leader
or oa:contributor
Both the schema:Person
and schema:Organization
types support a common set of properties that capture the basic information required
for publishing opportunity data.
Property | Status | Notes |
---|---|---|
@id |
REQUIRED | A URI providing a unique identifier for the resource |
schema:identifier |
OPTIONAL | A local identifier for the resource |
schema:url |
RECOMMENDED | A URL to the homepage or other page about the organisation |
schema:name |
REQUIRED | The name of the organisation |
schema:description |
OPTIONAL | A description of the organisation |
schema:logo |
OPTIONAL | The logo of an organisation |
The following example illustrates how to associate an schema:Organization
with an event:
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Tai chi Class",
"description": "A tai chi class intended for beginners",
"startDate": "2017-03-22T20:00:00-05:00",
"duration": "PT60M",
"organizer": {
"type": "Organization",
"url": "http://example.org/clubs/1",
"name": "Bath Tai Chi Club",
"logo": "http://www.example.org/clubs/1/logo.png" }
}
skos:ConceptScheme
) and Physical Activity (skos:Concept
)List of Physical Activities are controlled vocabularies published using the types and properties defined by the SKOS standard. That standard covers all the requirements outlined in the concept model, allowing:
The [OpenActive-Activity-List] provides an openly licensed standard activity list that can be used by publishers. But where a publisher needs to publish their own list, then they can use the properties defined in the SKOS specification, as follows:
Property | Status | Notes |
---|---|---|
@id |
REQUIRED | A URI providing a unique identifier for the resource |
dc:title |
REQUIRED | Title of the Activity List |
schema:description |
RECOMMENDED | Description of the activity list |
dc:license |
RECOMMENDED | Reference to the license under which the activity list has been published |
The following example illustrates the basic structure of an activity list:
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "ConceptScheme",
"url": "http://www.example.org/activity-list",
"title": "Activity List",
"description": "An example activity list",
"concepts": [{
"type": "Concept",
"prefLabel": "Martial Arts",
"narrower": {
"type": "Concept",
"prefLabel": "Tai Chi"
} }]
}
The concepts
property used in the above example is defined in the JSON-LD context published as part of the OpenActive Vocabulary ([OpenActive-Vocabulary]).
The following properties from the [SKOS] specification can be used to describe physical activities.
Property | Status | Notes |
---|---|---|
skos:prefLabel |
REQUIRED | Preferred label for referring to the physical activity. The preferred labels should be used when publishing data about the activities involved in an event. |
skos:altLabel |
OPTIONAL | Alternative labels for the physical activity |
skos:inScheme |
RECOMMENDED | Refers to the Activity List in which this physical activity is defined. |
skos:broader |
OPTIONAL | 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". |
skos:narrower |
OPTIONAL | 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" |
skos:notation |
OPTIONAL | Provides a unique code or identifier for an activity |
The following markup illustrates how to describe a single activity.
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Concept",
"url": "http://www.example.org/activity-list#tai-chi",
"prefLabel": "Tai Chi",
"altLabel": "Tai-Chi",
"inScheme": "http://www.example.org/activity-list"
}
schema:Offer
)To indicate that a schema:Event
is only available to paid attendees, opportunity data provides may include details of the offers available to participants. The schema:Offer
type
provides some basic properties for indicating the price and availability of Offers.
Property | Status | Notes |
---|---|---|
@id |
REQUIRED | A URI providing a unique identifier for the resource |
schema:identifier |
OPTIONAL | A local identifier for the resource |
schema:name |
REQUIRED | The name of the offer suitable for display to participants |
schema:price |
REQUIRED | The offer price available to participants |
schema:priceCurrency |
REQUIRED | The currency of the offer price. |
The following example shows an event which offers a price for attending a single session.
{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Tai chi Class",
"description": "A tai chi class intended for beginners",
"duration": "PT60M",
"offers": [{
"name": "Single session",
"price": "5",
"priceCurrency": "GBP"
}]}
Schema.org provides additional properties for describing Offers. The above model highlights the properties that support the most common, basic use case. Future versions of this specification may include more detail around describing offers.
oa:ActivityOpportunity
)As described earlier in this specification, an Activity Opportunity is similar to an Event except it does not take place at a specific time: individual participants will decide when they will take part in the physical activity.
The oa:ActivityOpportunity
type will be used to represent these opportunities.
Information about Activity Opportunities can be published using the same set of properties that have been identified for Describing Events.
However applications MUST not use the schema:schedule
, schema:startDate
and schema:endDate
properties on this type of resource.
The previous sections describe how to publish opportunity data using a combination of existing and new vocabularies. But this approach may not address every requirement. Specific applications may need custom extensions and the community may need to revise or improve the core model presented here.
Future versions of the specification may have a wider scope, e.g. to support description of facilities, equipment, event booking or accreditation schemes for sporting organisations.
With this in mind, the following sections briefly outline some expected ways in which this specification and the practice of publishing of opportunity data may evolve.
To support changing practice, consumers of opportunity data SHOULD be liberal in what they accept from data publishers, to allow the use of additional properties.
The broad goal is to ensure that future versions of this specification remain backwards compatible. This will ensure that published data remains valid.
New types of resource, relationships and properties can easily be added to extend the model without impacting existing data. Potential breaking changes would include changing the definitions of existing properties, or removing them from the specification.
To avoid this, the goal will be to:
Proposed changes to the specification will also be communicated in advance of their formal release, through the sharing of public Editor's Drafts. This will provide opportunities for both publishers and users of the data to update their applications.
To support additional testing and experimentation around new properties, a "beta" namespace has been defined to allow the community to explore extensions to this specification in a controlled way. For more information on the process supporting that see [OpenActive-Beta-Namespace].
Regardless of the type of extension, activity can continue to be co-ordinated within the OpenActive Community Group as the primary forum for standardising the publication of opportunity data.
This specification draws heavily on [SCHEMA-ORG] and [SKOS] to define its core data model. Both of these specifications define additional properties that are not directly referenced in this document.
However data publishers are free to use any additional types and properties where useful. [SCHEMA-ORG] in particular provides a source of a wide range of additional properties for describing Events, Places, Organisations, etc.
For example an application may wish to share reviews of events, places or clubs. The schema:review
property and its related data model can be used for this purpose, without requiring
revisions to this specification.
There may be a need for new vocabulary to support the needs of specific applications or user communities. Where these are widely relevant then these extensions might be included in this data model.
In other circumstances its expected that additional data models and specifications will be produced to support the needs of those communities. For example it may be useful to define standard models for describing the characteristics of cycle tracks or orienteering trails. These would be better defined either as custom vocabularies or proposed as [SCHEMA-ORG] extensions.
Where an application or community is defining a custom vocabulary then they SHOULD:
[JSON-LD] allows data to be published with reference to multiple contexts. This will help clarify for reusers where a dataset is combining this specification with one or more custom vocabularies.
This section is non-normative.
The editors thank all members of the OpenActive CG for contributions of various kinds.