Modelling Opportunity Data 2.1

4.1 Data Model Diagram

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

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

• Martial Arts
  • Karate
  • Kendo
  • Judo

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

• Team Sports
  • Football
  • Water Polo
• Water Sports
  • Swimming
  • Water Aerobics
  • Water Polo

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.

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.

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.

For some scheduled events, participants may not have to commit to attending every session. They can drop-in for individual classes, or build up a regular habit to improve their fitness. For other events, like a course, there is might be an expectation that a participant will attend every class.

Some large scale events, such as a family fun day, might consist of a programme of smaller scheduled events that take place over the course of a single or multiple days.

In order to simplify terminology in this specification we use the term "Event" to refer to all types of opportunities, including one-off and regularly occurring events. However in the detailed data model we distinguish between some types of events to allow data users to better present opportunities to potential participants.

Regardless of what type of an event is being described, there is a range of additional information that may help describe the event to potential participants. This includes:

• the Physical Activity or Activities that will take place at the event
• the location (Place or Venue) in which it is taking place
• the Organiser of the event, which might be a person or an organisation
• the Programme used to structure the event
• descriptive attributes, such as its suitability for specific age or weight ranges
• general category information to tag the event as suitable for certain fitness levels, intensity, etc
• booking information, including price, attendance numbers and method of booking

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.

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:

• A gym class may take place in a leisure centre at a specific address or other precisely defined location
• A cycling or walking event might start at a specific location, but will subsequently follow a route
• An exercise or running group might meet in an area of a local park, rather than at a specific address

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:

• a description, e.g. "Meet by the lake, in Victoria Park"
• an address
• a venue, such as a leisure centre, which might have an address and/or a latitude or longitude
• a facility within a larger venue, e.g. a football pitch which is part of a leisure centre

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:

• a name
• an address and/or geographic coordinates
• opening hours

4.6 Programmes and Brands

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 means of organising and running 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:

• Les Mills BodyPump
• Learn to Row, from British Rowing
• Back to Netball, from England Netball

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

4.8 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:

• basic descriptive attributes of the product, such as its name, description, etc
• the activity or activities for which the facility is to be used
• the location of the facility
• an offer to use the facility, for a specific price
• the Slots during which the product is available, including any associated offers

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.

4.9 Route Guidance

In addition to Events and Facilities hosted by leisure or recreational operators, opportunities for exercise may alse be presented by outdoor trails and pathways suitable for e.g. walking, cycling, horse-riding, etc. For the purposes of this specification, such trails and pathways are referred to as Routes, and information about them as Route Guidance.

In the OpenActive context, Routes are considered to be a geographical entity: that is to say, the path or trail itself, as characterised by distance, terrain, elevation, and other strictly geographical data points. Route Guidance, by contrast, consists of information users might find helpful in accessing or engaging with the Route, for instance its starting point, degree of challenge, points of interest, etc.

Note that modelling of Routes themselves is beyond the current scope of this specification, beyond basic provision of a .gpx file or similar for pathfinding. Route Guidance, however, is within scope, with the intention that such Metadata objects should give users all the information necessary for them to engage with the activity opportunity the Route presents.

Note that Route Guidance objects may exist either as attributes of a scheduled Event or Session (acting as an amenity or resource supporting a planned activity), or as self-standing entitites (simply indicating the existence or availability of a Route for use).

5.1 Namespaces

The rest of this specification makes use of the following namespaces:

dc:

http://purl.org/dc/terms/

schema:

https://schema.org/

skos:

http://www.w3.org/2004/02/skos/core#

geo:

http://www.w3.org/2003/01/geo/wgs84_pos#

oa:

https://openactive.io/

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

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:

• a direct link to the resource that avoids redirects
• a stable link that will resolve to a public web page, accessible to both web browsers and applications
• a consistent link that will allow reusers to rely on the URL as an identifier, e.g. to merge in updated data

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, e.g. as a reference to an API endpoint. 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 other identifiers for a resource, e.g. a company or registration number for an Organization, or an internal identifier for an Event. Other public identifiers can be via a schema:PropertyValue. 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 the schema:url 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://openactive.io/",
    "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. Some properties have been marked as RECOMMENDED. Publishers SHOULD provide these properties if it is feasible to do so, as they will improve the quality and usability of their data.

Where data is not available to populate RECOMMENDED and OPTIONAL properties, publishers MUST exclude these from their data. Published data MUST not include properties with null values, empty strings or empty arrays.

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 Controlled Vocabularies

When the value of a property might be one of a fixed set of values, it can be useful to publish that list of values as a "controlled vocabulary".

This allows a publisher to publish the list of values, with supporting documentation and definitions in a machine-readable format. We use the existing [SKOS] standard as a means of publishing these vocabularies.

A number of properties in this data model allow data publishers to use values from a controlled vocabulary, e.g. oa:activity, oa:level, oa:category, etc.

Publishers SHOULD publish the controlled vocabularies referenced from their data in a machine-readable format, under an open licence.

The OpenActive Community group MAY create and recommend the use of specific controlled vocabularies to help improve the consistency of how data is published.

Publishers SHOULD use values from standard vocabularies where available.

For example, the community group is developing a controlled vocabulary that defines a standard activity list. Values from this vocabulary can be used in the oa:activity property.

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.6 Describing Events (schema:Event)

The Schema.org [schema:Event](https://schema.org/Event) type corresponds to the definition of Event given earlier in this specification. The properties and relationships associated with the [schema:Event](https://schema.org/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.

The following example shows a simple event description, including its start time and duration:

  {
    "@context": "https://openactive.io/",
    "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://openactive.io/",
    "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",
  "addressCountry": "GB",
  "addressRegion": "Somerset",
  "postalCode": "BS1 4SD"
}
    }
  }

  {
    "@context": "https://openactive.io/",
    "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://openactive.io/activity-list#c16df6ed-a4a0-4275-a8c3-1c8cff56856f",
"type": "Concept",
"prefLabel": "Tai Chi",
"inScheme": "https://openactive.io/activity-list"
    }]
  }

  {
    "@context": "https://openactive.io/",
    "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
  }

  {
    "@context": "https://openactive.io/",
    "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": "https://schema.org/EventCancelled"
  }

  {
    "@context": "https://openactive.io/",
    "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": [{
"type": "Concept",
"prefLabel": "Beginner"
    }]
  }

  {
    "@context": "https://openactive.io/",
    "type": "Event",
    "url": "http://www.example.org/events/1",
    "name": "Back to Netball",
    "description": "A slightly more energetic way to get back in to Netball if you’ve had a break from the sport or for those who’d like to give something new a go. This is based on the traditional 7 a-side netball game and involves running and jumping. It’s a fun light hearted session, where we do netball skills (a bit of fitness – not too much!) and match play. We have players of all ages and abilities ranging from players in their 20’s through to 50’s!",
    "attendeeInstructions": "Just wear proper trainers, comfy clothes and bring a drink.",
    "startDate": "2017-04-01T08:00:00Z",
    "duration": "PT60M",
    "programme": {
"type": "Brand",
"name": "Back to Netball",
"url": "https://www.englandnetball.co.uk/backtonetball/",
"description": "Running across England since 2010, over 60,000 women have taken part in Back to Netball and realised the benefits of getting involved.",
"logo": {
  "type": "ImageObject",
  "url": "http://hertsnetball.co.uk/js/plugins/imagemanager/files/B2N_logo.jpg"
}
    }
  }

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

  {
    "@context": "https://openactive.io/",
    "type": "Event",
    "url": "http://www.example.org/events/1",
    "name": "Exercise in the park",
    "ageRange": {
 "type": "QuantitativeValue",
 "minValue": 0
    }
  }

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

  {
    "@context": "https://openactive.io/",
    "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"
  }

  {
    "@context": "https://openactive.io/",
    "type": "HeadlineEvent",
    "url": "http://www.example.org/events/1",
    "name": "Aquathlon Day",
    "description": "A day of aquathlon races",
    "startDate": "2018-09-01T09:00:00-05:00",
    "endDate": "2018-09-01T17:00:00-05:00",
    "duration": "P1D",
    "subEvent": [
{
  "type": "Event",
  "url": "http://www.example.org/events/2",
  "name": "Aquathlon Sprint",
  "startDate": "2018-09-01T10:00:00-05:00"
},
{
  "type": "Event",
  "url": "http://www.example.org/events/2",
  "name": "Aquathlon Long Course",
  "startDate": "2018-09-01T14:00:00-05:00"
}
    ]
  }

  {
    "@context": "https://openactive.io/",
    "type": "SessionSeries",
    "url": "http://www.example.org/events/1",
    "name": "Wednesday Yoga",
    "description": "Yoga on a Wednesday",
    "startDate": "2018-01-01",
    "endDate": "2018-12-31"
    "subEvent": [
{
  "type": "ScheduledSession",
  "url": "http://www.example.org/events/2",
  "startDate": "2018-09-05T18:00:00-05:00",
  "endDate": "2018-09-05T19:00:00-05:00",
  "duration": "PT1H"
},
...
    ]
  }

  {
    "@context": "https://openactive.io/",
    "type": "HeadlineEvent",
    "url": "http://www.example.org/events/1",
    "name": "Aquathlon Day",
    "description": "A day of aquathlon races",
    "startDate": "2018-09-01T09:00:00-05:00",
    "endDate": "2018-09-01T17:00:00-05:00",
    "duration": "P1D",
    "subEvent": [
{
  "type": "Event",
  "url": "http://www.example.org/events/2",
  "name": "Aquathlon Sprint",
  "startDate": "2018-09-01T10:00:00-05:00"
},
{
  "type": "Event",
  "url": "http://www.example.org/events/3",
  "name": "Aquathlon Long Course",
  "startDate": "2018-09-01T14:00:00-05:00"
}
    ]
  }

  {
    "@context": "https://openactive.io/",
    "type": "CourseInstance",
    "url": "http://www.example.org/events/1",
    "name": "Sailing Course",
    "description": "A ten week sailing course",
    "startDate": "2018-08-30",
    "endDate": "2018-11-08"
    "subEvent": [
{
  "type": "Event",
  "url": "http://www.example.org/events/2",
  "startDate": "2018-08-30T09:00:00-05:00",
  "endDate": "2018-08-30T10:00:00-05:00",
  "duration": "PT1H"
},
...
    ]
  }

  {
    "@context": "https://openactive.io/",
    "type": "EventSeries",
    "url": "http://www.example.org/events/1",
    "name": "Swim For Adults",
    "description": "Adult swimming session",
    "activity": [{
    "type": "Concept",
    "prefLabel": "Swimming"
    }],
    "subEvent": [
{
  "type": "SessionSeries",
  "url": "http://www.example.org/events/2",
  "name": "Swim For Adults",
  "location": {
    "type": "Place",
    "name": "ExampleCo Gym"
    ...
  },
  "eventSchedule": [
    {
"type": "Schedule",
"startDate": "2017-01-01",
"endDate": "2017-12-31",
"repeatFrequency": "P1W",
"byDay": [ "https://schema.org/Wednesday" ],
"startTime": "19:00",
"endTime": "20:00",
"duration": "PT1H",
"scheduledEventType": "ScheduledSession"
    }
  ]
},
{
  "type": "SessionSeries",
  "url": "http://www.example.org/events/2",
  "name": "Swim For Adults",
  "location": {
    "type": "Place",
    "name": "A. N. Other Gym"
    ...
  },
  "eventSchedule": [
    {
"type": "Schedule",
"startDate": "2017-01-01",
"endDate": "2017-12-31",
"repeatFrequency": "P1W",
"byDay": [ "https://schema.org/Thursday" ],
"startTime": "18:00",
"endTime": "20:00",
"duration": "PT2H",
"scheduledEventType": "ScheduledSession"
    }
  ]
}
    ]
  }

  {
    "@context": "https://openactive.io/",
    "type": "SessionSeries",
    "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": [ "https://schema.org/Wednesday" ],
  "startTime": "19:00",
  "endTime": "20:00",
  "duration": "PT1H",
  "scheduledEventType": "ScheduledSession"
}
    ]
  }

5.7 Describing Locations (schema:Place)

This specification recommends use of the schema:Place and schema:SportsActivityLocation types for describing locations.

The schema:location property can be used to relate an schema:Event or oa:FacilityUse to a Place.

The following table lists a number of properties that can be used to describe a schema:Place.

The following example illustrates a simple place description including its name, address, telephone number and website.

  {
    "@context": "https://openactive.io/",
    "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",
  "addressRegion": "Somerset",
  "postalCode": "BA2 4ET",
  "addressCountry": "GB"
    },
    "telephone": "+44 (0)1225 486905"
  }

  {
    "@context": "https://openactive.io/",
    "type": "PostalAddress",
    "streetAddress": "North Parade Road",
    "addressLocality": "Bath",
    "addressRegion": "Somerset",
    "postalCode": "BA2 4ET",
    "addressCountry": "GB"
  }

  {
    "@context": "https://openactive.io/",
    "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",
  "addressRegion": "Somerset",
  "postalCode": "BA2 4ET",
  "addressCountry": "GB"
    },
    "telephone": "+44 (0)1225 486905",
    "geo": {
"type": "GeoCoordinates",
"latitude": 51.3816123,
"longitude": -2.3544367
    }
  }

  {
    "@context": "https://openactive.io/",
    "type": "Place",
    "amenityFeature": [
 {
    "type": "ChangingFacilities",
    "name": "Changing Facilities",
    "value": true
 }
    ]
  }

  {
    "@context": "https://openactive.io/",
    "type": "Place",
    "amenityFeature": [
 {
    "type": "LocationFeatureSpecification",
    "name": "Outdoor seating",
    "value": true
 }
    ]
  }

  {
    "@context": "https://openactive.io/",
    "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",
  "addressRegion": "Somerset",
  "postalCode": "BA2 4ET",
  "addressCountry": "GB"
    },
    "containsPlace": [{
"type": "SportsActivityLocation",
"url": "http://www.better.org.uk/leisure-centre/banes/bath-sports-and-leisure-centre/gym",
"name": "Gym"
    }]
  }

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

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:

• organized by an club (schema:organizer)
• be led by a specific coach (oa:leader)
• and involve other named participants (oa:contributor)

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

• For events taking place in a gym, the organizer should be listed as the gym (an schema:Organization)
• For "user generated" events in a booking system, the organizer should be the account under which the events were created, rather than the booking system. The instructor for the event can be specified as the oa:leader or oa:contributor
• For franchised events (e.g. Clubbercise), the organiser should be the franchisee, as they are ultimately responsible for organising that specific event

Both the schema:Person and schema:Organization types support a common set of properties that capture the basic information required for publishing opportunity data.

The following example illustrates how to associate an schema:Organization with an event:

  {
    "@context": "https://openactive.io/",
    "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": [{
    "type": "ImageObject",
    "url": "http://www.example.org/clubs/1/logo.png"
}]
    }]
  }

5.9 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:

• activities to be organised into hierarchies to capture broader-narrow relationships, e.g. "Martial Arts" and "Judo"
• sharing of alternative labels to support search and indexing
• the sharing of standard codes to support data integration

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:

The following example illustrates the basic structure of an activity list:

  {
    "@context": "https://openactive.io/",
    "type": "ConceptScheme",
    "id": "http://www.example.org/activity-list",
    "url": "http://www.example.org/activity-list",
    "title": "Activity List",
    "description": "An example activity list",
    "concept": [{
"type": "Concept",
"prefLabel": "Martial Arts",
"narrower": {
  "type": "Concept",
  "prefLabel": "Tai Chi"
}
    }]
  }

  {
    "@context": "https://openactive.io/",
    "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.10 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.

The following example shows an event which offers a price for attending a single session.

  {
    "@context": "https://openactive.io/",
    "type": "Event",
    "url": "http://www.example.org/events/1",
    "name": "Tai chi Class",
    "description": "A tai chi class intended for beginners",
    "duration": "PT60M",
    "offers": [{
"type": "Offer",
"name": "Single session",
"price": 5,
"priceCurrency": "GBP"
    }]
  }

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

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

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

A Facility Use is a subclass of schema: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.

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.

  {
    "@context": "https://openactive.io/",
    "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",
    "provider": {
"type": "Organization",
"name": "Leisure Centre Ltd"
    },
    "location": {
"type": "Place",
"name": "Example Leisure Centre",
"address": {
  "type": "PostalAddress",
  "streetAddress": "1 High Street",
  "addressLocality": "Bristol",
  "addressRegion": "Somerset",
  "postalCode": "BS1 4SD",
  "addressCountry": "GB"
}
    },
    "offers": [
  {
    "type": "Offer",
    "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": [
 {
    "type": "Offer",
    "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 property provides more detail on the location. The example describes two Slots, but the second is no longer available.

  {
    "@context": "https://openactive.io/",
    "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": [
 {
   "type": "ImageObject",
   "url": "http://example.org/images/1.jpg"
 }
    ],
    "activity": "Tennis",
    "provider": {
"type": "Organization",
"name": "Leisure Centre Ltd"
    },
    "location": {
"type": "SportsActivityLocation",
"name": "Main Tennis Court",
"containedInPlace": {
   "type": "Place",
   "name": "Example Leisure Centre",
   "address": {
     "type": "PostalAddress",
     "streetAddress": "1 High Street",
     "addressLocality": "Bristol",
     "addressRegion": "Somerset",
     "postalCode": "BS1 4SD",
     "addressCountry": "GB"
   }
}
    },
    "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
  }
    ]
  }

5.13 Describing Route Guidance (oa:RouteGuidance)

The purpose of the Route Guidance model is to describe a Route: that is to say, while it concerns and points to geographic information, it is not itself a geo-information type.

Route Guidance is often generated over an extended period of curation: that is to say, initially sparse information about a Route is frequently augmented over time, until a full description of the Route emerges. While the Route Guidance model is rich, then, the number of REQUIRED fields is relatively small, in keeping with this curation workflow.

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

  {
    "@context": [
"https://openactive.io/",
"https://example.org/custom.jsonld"
    ],
    "type": "Event",
    "ext:myCustomProperty": "foo"
  }