Abstract

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.

Status of This Document

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 [email protected] (subscribe, archives).

1. Introduction

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.

1.1 Categories of Physical Activity Data

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.

Fig. 1 Types of physical activity data

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.

1.2 Requirements

This specification has been developed to meet a broad set of requirements.

1.2.1 Support all types of opportunity data

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

1.2.2 Support discovery of opportunities

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.

1.2.3 Support all physical activities

The specification should be inclusive and support sharing of opportunity data about all types of physical activities, not just sports.

1.2.4 Allow sharing of activity lists

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

1.2.5 Support a variety of sources

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.

1.2.6 Be agnostic to formats and APIs

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.

1.2.7 Create an extensible framework

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.

1.3 Scope

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.

1.4 Structure of this document

This specification is divided into two main sections:

  1. Introduction - provides a broad definition of opportunity data and goals for this specification
  2. Key Concepts - describes the key types of resources relevant to opportunity data, along with their relationships and common attributes
  3. Data Model - a data model that maps the key concepts to some standard vocabularies

2. Conformance

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, SHOULD, and SHOULD NOT 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].

3. Typographical Conventions

The following typographic conventions are used in this specification:

markup
Markup (elements, attributes, properties), machine processable values (string, characters, media types), property name, or a file name is in a monospace font.
definition
A definition of a term, to be used elsewhere in this or other specifications, is in bold and italics.
hyperlink
A hyperlink is underlined and in blue.
[reference]
A document reference (normative or informative) is enclosed in square brackets and links to the references section.

Note
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.

Example 1
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.

4. Key Concepts

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.

4.1 Data Model Diagram

This diagram illustrates the resources and relationships that are introduced in the following sections.

Fig. 2 Opportunity data schema diagram

4.2 Physical Activities

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.

Note
The proposed model for Activity Lists is based on the [SKOS] standard for publishing controlled vocabularies.
Note
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.
Note

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].

4.3 Events

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:

Note

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.

4.4 Organisers (Persons and Organizations)

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.

Note

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.

4.5 Places

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.

A Sports Activity Location is a type of Place that is used to describe a facilities within a broader Place.

Places may have additional descriptive properties, for example:

4.6 Programmes

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).

4.7 Activity Opportunities

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.

4.8 Offers

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.

Note

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.

4.9 Facility Use and Slots

Not all opportunities to be physically active are scheduled Events. Leisure centres and other locations also provide facilities (e.g. squash courts, pitches, table tennis tables) that are available for use by participants.

To manage demand these facilities are usually available for hire at specific times of day. These are referred to as Slots. A Slot is an opportunity to use a facility at a specific time and a specific duration, e.g. from 10am for 30 minutes

Some facilities are permanent parts of a leisure centre (or other Place). For example tennis courts, football pitches, etc.

But many leisure centres have flexibility to reconfigure their spaces to support different, often mutually exclusive ways. For example an individual sports hall might be used as either a single indoor 5-a-side pitch, or as two separate badminton courts.

Modelling the potential configurations of these spaces is outside the scope of this specification. The community group has chosen to take a more user centred view of describing opportunities to use facilities. This supports our primary use case of enabling the discovery of opportunities.

A Facility Use is a product that is offered to potential participants. It reflects the ability to use or hire a facility at a specific location. A platform can publish data about the range of products on offer at a location, updating their availability as facilities are booked by participants.

The following properties will help to describe the specific Facility Use product on offer:

Some facility use products are opportunities to use a individual, identifiable facility, e.g. Tennis Court 1. These are referred to a as Individual Facility Uses. The location of these products will be a Sports Activity Location.

Otherwise, a Facility Use will describe an oppirtunity to use less permanent facilities, e.g. a table tennis table that will be moved into a sports hall on demand, or for an unnamed facility that will be allocated by a platform during booking. In this case the location will be for the Place in which the facility is available.

Facilities may be offered for use at a single price at any time of day, or the price may vary depending on on which Slot is used.

As the use of facility is a self-directed activity it will differ from an Event in that is will not be lead, coached, etc.

5. Data Model

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.

Note
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.

5.1 Namespaces

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/
Note

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.

5.2 Data Model Overview

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.

5.3 Identifying and Linking Resources

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:

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.

Example 2: Simple event description

{
"@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.

5.4 Required and Optional Properties

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.

5.5 Describing Events (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 schema:Date or schema:DateTime.

While this property is marked as OPTIONAL, a data publisher MUST provide either a schema:startDate or specify a oa:schedule for an event.

schema:endDate OPTIONAL

The end date and time of the event. Can be specified as a schema:Date or schema:DateTime

It is RECOMMENDED that publishers provide either an schema:endDate or a schema:duration for an event.

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 schema:Place complete with a fully described geographic location and/or address.

If only an address is available then this SHOULD be described as a schema:PostalAddress.

Applications MAY use schema:Text to provide a more general description of a location ("In Victoria Park, near the lake"), but this is not recommended: consuming applications will be unable to help users discover opportunities based on their location.

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.
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. Specified as a QuantifiedValue with minValue and maxValue properties
oa:genderRestriction OPTIONAL Indicates that an event is restricted to Male, Female or a Mixed audience. Values should be one of the three URIs defined by this specification (see below). 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:

Example 3: Simple event description

{
"@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.

Example 4: Adding a venue and an 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" } }
}

5.5.1 Relating Events to Physical Activities

The oa:activity property allows an event to be associated with one or more Physical Activities. Its simplest usage is as follows:

Example 5: Specifying activities

{
"@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"
}

This specifies that the event will involve Tai Chi. Multiple activities can be specified by using repeated values:

Example 6: Specifying multiple activities

{
"@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:

Example 7: Using activities from an Activity List

{
"@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.

5.5.2 Categorising events

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.

Example 8: Tagging 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",
"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.

Note
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.

5.5.3 Describing Event Suitability

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:

  • suited for a specific age range
  • suited for people with specific levels of experience (oa:level)
  • restricted to a male, female or mixed audience
5.5.3.1 Age Ranges

Age ranges are specified using the oa:ageRange property. The value is a schema:QuantifiedValue which should have minValue or maxValue properties. These properties specify an inclusive minimum and maximum age range for participants.

Data publishers using the oa:ageRange property MUST ensure that it has:

Data consumers SHOULD assume that:

  • if there is no ageRange property for an Event, then the event is suitable for adults only. E.g. as if the minValue has been specified as 18
  • if an ageRange is provided without a minValue property, then there is no minimum age for the Event
  • if an ageRange is provided without a maxValue property, then there is no maximum age for the Event
  • if an ageRange is provided with a minValue of 0, and there is no maxValue property then the Event is suitable for all

The following example illustrates how to specify an Event that is suitable for people aged 60 or over.

Example 9: Age range example

{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Tai chi Class",
"ageRange": {
   "type": "QuantifiedValue",
   "minValue": 60
}
}

The following example illustrates an Event that is suitable for all ages. This is indicated by providing an minValue property with a value of zero and no maxValue property.

Example 10: Age range - suitable for all example

{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Exercise in the park",
"ageRange": {
   "type": "QuantifiedValue",
   "minValue": 0
}
}
5.5.3.2 Gender Restriction

Attendance at some events is limited to certain audiences. For example a female only gym class. The oa:genderRestriction property can be used to specify these restrictions.

Data publishers using this property MUST use one of the following values:

If the genderRestriction property is not supplied for an Event, then data consumers SHOULD NOT assume a default value, the value should be treated as null. When searching or filtering for gender restricted Events, data consumers SHOULD remove Events with a null value. Invalid values for the genderRestriction property SHOULD be treated as null.

Example 11: Gender restriction example

{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Event",
"url": "http://www.example.org/events/1",
"name": "Gym class",
"genderRestriction": "http://www.openactive.io/ns#Female"
}

5.5.4 Adding programmes

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:

Example 12: Tagging 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:00Z",
"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:

Example 13: Tagging 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:00Z",
"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!"
}
}

5.5.5 Describing scheduled events

Note
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 to associate an Event with a schema:Schedule. The data describes a Tai Chi class that occurs every Wednesday at 7pm

Example 14: Adding an event schedule

{
"@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",
   "repeatFrequency": "P1W",
   "byDay": "http://schema.org/Wednesday",
   "startTime": "19:00Z",
   "endTime": "20:00Z"
}
}

5.5.6 Describing event availability

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.

Example 15: Basic event availability

{
"@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
}

5.5.7 Indicating the status of an event

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:

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:

Example 16: A cancelled 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",
"eventStatus": "http://schema.org/EventCancelled"
}

5.5.8 Describing support for disabilities at events

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:

Examples of using these are shown below:

Example 17: Accessibility information

{
"@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"
}

5.6 Describing Locations (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:

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.

5.6.1 Describing Addresses

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:

Example 18: An Address

{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "PostalAddress",
"streetAddress": "North Parade Road",
"addressLocality": "Bath",
"region": "Somerset",
"postalCode": "BA2 4ET"
}

5.6.2 Describing Places

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.
schema:amenityFeature OPTIONAL Used to indicate whether specific amenities are available at a location. The value of this property will be an array of schema:LocationFeatureSpecification objects. See "Describing Amenities" for more information.

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:

Example 19: Describing a 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:

Example 20: Locating a 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",
"geo": {
  "type": "GeoCoordinates",
  "latitude": "51.3816123",
  "longitude": "-2.3544367"
}
}

5.6.3 Describing Amenities

It can be useful to describe the amenities (e.g. characteristics, services or other features) available at a location.

Schema.org provides the schema:amenityFeature property for specifying an list of amenities that are available or unavailable at a specific schema:Place. The value of a the property is an array of objects that describe the individual amenities.

To improve consistency in how amenities are published, this specification defines some common types of amenities:

Publishers SHOULD use one of these types when applicable. If there is no pre-defined type then data publishers MUST use the more generic schema:LocationFeatureSpecification type.

This avoids the need for data consumers to have to rely on the name value to identify common amenities that may otherwise be named differently (e.g. "Changing Rooms, "Changing Facilities", etc).

Example 21: Amenity example

{
"type": "Place",
"amenityFeature": [
   {
      "type": "ChangingRooms",
      "name": "Changing Facilities",
      "value": true
   }
]
}

Publishers MUST include the type, name and value properties for each amenity. A value of false indicates that a specific amenity is not available.

Additional information MAY be provided about each of the amenities, using properties from the schema:LocationFeatureSpecification type. For example, specifying opening hours (schema:hoursAvailable) or to add a description (schema:description).

The list of pre-defined amenties MAY be revised in future specifications based on feedback from the community.

In the meantime additional types of amenities can be specified using the more generic schema:LocationFeatureSpecification type as shown below:

Example 22: Generic amenity type example

{
"type": "Place",
"amenityFeature": [
   {
      "type": "LocationFeatureSpecification",
      "name": "Outdoor seating",
      "value": true
   }
]
}

5.6.4 Describing Facilities

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:

Example 23: Describing a 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"
},
"containsPlace": {
  "type": "SportsActivityLocation",
  "url": "http://www.better.org.uk/leisure-centre/banes/bath-sports-and-leisure-centre/gym",
  "name": "Gym"
}
}

5.7 Describing Organisers (schema:Person and schema:Organization)

Note

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:

To help ensure that publishers apply these properties in consistent ways, it is recommended that:

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:

Example 24: Specifying an organiser

{
"@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"
} }

5.8 Describing Activity Lists (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:

Example 25: Publishing 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]).

5.8.1 Describing Physical Activities

The following properties from the [SKOS] specification can be used to describe physical activities.



Property Status Notes
@id OPTIONAL A URI providing a unique identifier for the resource
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.

Example 26: Publishing an activity list

{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "Concept",
"id": "http://www.example.org/activity-list#tai-chi",
"prefLabel": "Tai Chi",
"altLabel": "Tai-Chi",
"inScheme": "http://www.example.org/activity-list"
}

5.9 Describing Offers (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.

Example 27: Describing an Offer

{
"@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"
}]
}
Note
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.

5.10 Describing Slots (oa:Slot)

A Slot is an opportunity to use a facility at a specific time and for a specified duration. A Slot is therefore a specific type of Event, although it has a more constrained set of properties.

A series of Slots describes a calendar during which a facility is available for use.

Slots are always associated with a oa:FacilityUse product which may link to more detail about the facility on offer and the costs for hire.






Property Status Notes
@id REQUIRED A URI providing a unique identifier for the resource
schema:identifier OPTIONAL A local identifier for the resource
oa:facilityUse REQUIRED

Links a specific Slot with the oa:FacilityUse of which it is a part.

schema:startDate REQUIRED

The start date and time of the slot. Can be specified as a schema:Date or schema:DateTime.

schema:endDate OPTIONAL

The end date and time of the event. Can be specified as a schema:Date or schema:DateTime

schema:duration REQUIRED The duration of the event given in [ISO8601] format.
schema:offers OPTIONAL Describes offers to book and use this specific slot. If unspecified, then a client SHOULD use offers associated with the related Facility Use.
oa:remainingUses REQUIRED

Used to indicate the availability of this Slot. Where a Slot describes the opportunity to use a single facility this property should have a value of 0 or 1. Where a Slot describes the opportunity to use one of several facilities, which will be allocated during booking, then the property specific how many such facilities are remaining, and may then have a value greater than 1.

oa:maximumUses OPTIONAL

Where a Slot describes the opportunity to use one of several facilities, which will be allocated during booking, then this value can be used to indicate how many facilities might be available.

Examples of describing a Slot are given in the next section.

5.11 Describing Facility Use (oa:FacilityUse, oa:IndividualFacilityUse)

A Facility Use is a product. It describes an opportunity to use either one of a group of facilities (oa:FacilityUse) or a individual facility (oa:IndividualFacilityUse).

The opportunity to use a facility is divided into a calendar of Slots, which allow a participant to use that facility for a specified time and duration.

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 product
schema:identifier OPTIONAL A local identifier for the product
schema:name REQUIRED The name of the product or service
schema:description RECOMMENDED A free text description of the product or service
schema:image OPTIONAL An image or photo that depicts the product, e.g. a photo of the facility or equipment
oa:activity REQUIRED Specifies the physical activity or activities that can be performed when the facility is used.
schema:location REQUIRED The location of the facility being used. This will either be a generic location, e.g. a leisure centre or sports hall for equipment or more temporary spaces, or a specific schema:SportsActivityLocation when describing opportunities to use a specific identifiable facility (oa:IndividualFacilityUse)
schema:event REQUIRED An array of one or more upcoming slots (oa:Slot) during which the product can be used. E.g. a list of hourly slots during which a football pitch might be hired. Only minimal information need be provided about each event, e.g. identifiers, start time, duration, event status, and any associated offers. This will be sufficient to allow data users to build a timetable of slots, with an availability status, price, etc.
schema:offers OPTIONAL Describes a generic offer to use a facility, e.g to indicate it is available for a set price, or may be used for free. Where offers might vary based on time of day (e.g. peak pricing) then this information should be associated with the specific event ("slot")
schema:hoursAvailable OPTIONAL Specifies the hours during which this product is available. The value of this property is a schema:OpeningHoursSpecification.
oa:individualFacilityUses OPTIONAL Links a oa:FacilityUse product, describing a general opportunity to, e.g. book and play tennis at a leisure centre with an array of oa:IndividualFacilityUse products that provide a more detailed description about an opportunity to book, e.g. individual tennis courts. This allows a platform to publish both a general product and time-table as well as more detailed products for individual facilities.

The following example describes opportunities to use table tennis facilities at a leisure centre. By default use of a table is for 30 minutes and costs ten pounds.

However at specific times the cost to use a table increases. This is indicated by offers associated with the second Slot.

In both cases a maximum of four tables are available. In the example, only one table remains for use in the first slot, while the second has three.

Example 28: Describing use of a facility

{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "FacilityUse",
"url": "http://www.example.org/facility-use/1",
"name": "Example Leisure Centre Table Tennis",
"description": "Table tennis tables are available to hire for thirty minute slots",
"activity": "Table Tennis",
"location": {
  "type": "Place",
  "name": "Example Leisure Centre",
  "address": {
    "type": "PostalAddress",
    "streetAddress": "1 High Street",
    "addressLocality": "Bristol",
    "postalCode": "BS1 4SD"
  }
}, "offers": [ { "name": "30 minute hire", "price": "10", "priceCurrency": "GBP" } ], "event": [ { "type": "Slot",
"id": "http://www.example.org/facility-use/slots/1", "facilityUse": "http://www.example.org/facility-use/1", "startDate": "2018-03-01T10:00:00Z",
"duration": "PT30M",
"remainingUses": 1, "maximumUses": 4 }, { "type": "Slot",
"id": "http://www.example.org/facility-use/slots/2", "facilityUse": "http://www.example.org/facility-use/1", "startDate": "2018-03-01T11:00:00Z",
"duration": "PT30M",
"remainingUses": 3, "maximumUses": 4, "offers": [ { "name": "30 minute hire", "price": "15", "priceCurrency": "GBP" } ] } ] }

The following example shows how to use the data model to publish opportunities to hire a specific tennis court. As this is an oa:IndividualFacilityUse the location field provides more detail on the location. The example describes two Slots, but the second is no longer available.

Example 29: Describing use of an individual facility

{
"@context": "https://www.openactive.io/ns/oa.jsonld",
"type": "IndividualFacilityUse",
"url": "http://www.example.org/facility-use/2",
"name": "Play Tenns on the Main Tennis Court",
"description": "Tennis courts are available for 30 min sessions",
"image": [
   "http://example.org/images/1.jpg"
],
"activity": "Tennis",
"location": {
  "type": "SportsActivityLocation",
  "name": "Main Tennis Court",
  "containedInPlace": {
     "type": "Place",
     "name": "Example Leisure Centre",
     "address": {
       "type": "PostalAddress",
       "streetAddress": "1 High Street",
       "addressLocality": "Bristol",
       "postalCode": "BS1 4SD"
     }  
  }
},
"event": [
    {
      "type": "Slot",   
      "id": "http://www.example.org/facility-use/slots/1",
      "facilityUse": "http://www.example.org/facility-use/1",
      "startDate": "2018-03-01T10:00:00Z",   
      "duration": "PT30M",   
      "remainingUses": 1,
      "maximumUses": 1
    },
    {
      "type": "Slot",   
      "id": "http://www.example.org/facility-use/slots/1",
      "facilityUse": "http://www.example.org/facility-use/1",
      "startDate": "2018-03-01T11:00:00Z",   
      "duration": "PT30M",   
      "remainingUses": 0,
      "maximumUses": 1
    }
] 
}
Note

The community group feels that the data model proposed in this section adequately covers the primary use cases relating to publishing data on opportunities to hire and use facilities

However we recognise that there may be some consequences on the volume of data shared via RPDE feeds. Specifically, for multi-use facilities the booking of mutually exclusive configurations will end up increasing the volume of updates that need to be communicated to users.

The community group has documented this issue and requests feedback from publishers and users based on implementation feedback before deciding how to address the issue.

5.12 Describing Activity Opportunities (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.

5.13 Extending the Model

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.

5.13.1 Versioning Policy

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:

  • evolve the definitions of existing properties to broadly retain their current meaning and legal values.
  • deprecate, rather than remove properties that are judged, based on implementation experience, to be less useful or confusing. Deprecated properties will be clearly marked in both the human and machine-readable versions of the OpenActive namespace.
  • ensure that conformance criteria are loosely defined, balancing the need to be able to validate data against a desire to allow some evolution in practice

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.

5.13.2 Relationship with Schema.org and SKOS

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.

5.13.3 Defining Custom Vocabularies

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:

  • publish documentation that describes the custom properties, types and controlled vocabularies being used
  • create a custom [JSON-LD] schema that provides a machine-readable definition of the properties
  • share the documentation and schema with the OpenActive community group

[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.

A. Acknowledgements

This section is non-normative.

The editors thank all members of the OpenActive CG for contributions of various kinds.

B. References

B.1 Normative references

[RFC2119]
S. Bradner. IETF. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

B.2 Informative references

[ISO8601]
International Organization for Standardization (ISO). Representation of dates and times. ISO 8601:2004.. 2004. ISO 8601:2004. URL: http://www.iso.org/iso/catalogue_detail?csnumber=40874
[JSON-LD]
W3C. JSON-LD 1.0. W3C Recommendation. URL: https://www.w3.org/TR/json-ld/
[OpenActive-Activity-List]
OpenActive Community Group. OpenActive Activity List. URL: https://www.openactive.io/activity-list/
[OpenActive-Beta-Namespace]
OpenActive Community Group. OpenActive Beta Namespace. URL: https://www.openactive.io/ns-beta/
[OpenActive-Vocabulary]
OpenActive Community Group. OpenActive Vocabulary. URL: https://www.openactive.io/ns/
[Publishing-Opportunity-Data]
OpenActive Community Group. Publishing Opportunity Data: A Primer. URL: https://www.openactive.io/opportunity-data-primer/
[SCHEMA-ORG]
Schema.org. URL: http://schema.org/
[SKOS]
W3C. SKOS Simple Knowledge Organization System Primer. W3C Note. URL: https://www.w3.org/TR/skos-primer