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.

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:

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

Places may have additional descriptive properties, for example:

• a name
• an address and/or geographic coordinates
• opening hours
• a list of equipment that is available for people to use at that location

To help distinguish between equipment and facilities: facilities will be fixed features of a location, e.g. squash courts or a walking trail; equipment will be items like table tennis tables that may be moved around a facility.

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:

• 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 Activity Opportunities

Not all opportunities to be physically active are organised Events. Some opportunities are self-directed for example:

• following a designated walking route
• using a permanent (or temporary) orienteering course
• going for a ride on a mountain bike trail

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:

• they will involve one or more Physical Activities, e.g. mountain biking
• take place in a location, e.g. "Victoria Park Mountain Bike Trail"
• have other descriptive attributes, such as suitability for particular types of participants, fitness levels, etc.

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.

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/

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. When supplied, this URI MUST be stable and unchanging over time. Applications harvesting and indexing opportunity data SHOULD use this as the unique identifier for the resource
• schema:url - provides a link to a public web page about the resource. Further machine-readable metadata MAY be discoverable from that web page. Applications MUST be able to use this URL as a means for providing users with a link to more information about a resource
• schema:identifier - provides a means of sharing non-URI identifiers for a resource, e.g. a company or registration number for an Organization, or an internal identifier for an Event. Applications MAY use this as a unique identifier for the resource, if there is no @id available.

In short, the @id property provides a unique global identifier, while the schema:url provides a means to provide a link to a public web page about a resource.

If applicable then publishers may choose to use the same URI for these two properties. If an @id property is not provided then applications MAY choose to rely on the value of this property as a unique identifier.

The option to use two different URLs is useful when there is a need to distinguish between a unique identifier and a public resource. For example a platform hosting opportunity data may need to assign a unique identifier to a resource that is separate to its public web page.

{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "id": "http://host.opportunity-data.com/id/12345",
  "url": "http://my-leisure-centre.example.org/events/1",
  "name": "Tai chi Class"
}

In the above example the @id property provides a unique identifier across the hosting application. But the public URL for the Event uses a separate, customer-specific domain.

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.

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

{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "url": "http://www.example.org/events/1",
  "name": "Tai chi Class",
  "description": "A tai chi class intended for beginners",
  "attendeeInstructions": "Please wear trainers and comfortable clothing",
  "startDate": "2017-03-22T20:00:00-05:00",
  "duration": "PT60M"
}

This basic description can be improved by providing information about its location and organizer.

{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "url": "http://www.example.org/events/1",
  "name": "Tai chi Class",
  "description": "A tai chi class intended for beginners",
  "attendeeInstructions": "Please wear trainers and comfortable clothing",
  "startDate": "2017-03-22T20:00:00-05:00",
  "duration": "PT60M",
  "organizer": {
    "type": "Organization",
    "url": "http://example.org/orgs/bristol-tai-chi",
    "name": "Bristol Tai Chi"  },
  "location": {
    "type": "Place",
    "name": "ExampleCo Gym",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "1 High Street",
      "addressLocality": "Bristol",
      "postalCode": "BS1 4SD"
    }
  }}

{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "url": "http://www.example.org/events/1",
  "name": "Tai chi Class",
  "description": "A tai chi class intended for beginners",
  "startDate": "2017-03-22T20:00:00-05:00",
  "duration": "PT60M",
  "oa:activity": "Tai chi"
}

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

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

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

{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "url": "http://www.example.org/events/1",
  "name": "Tai chi Class",
  "description": "A tai chi class intended for beginners",
  "startDate": "2017-03-22T20:00:00-05:00",
  "duration": "PT60M",
  "ageRange": 60,
  "genderRestriction": "mixed"
}

{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "url": "http://www.example.org/events/1",
  "name": "Rowing Class",
  "description": "A rowing class for beginners",
  "startDate": "2017-04-01T08:00:00",
  "duration": "PT60M",
  "level": ["Beginner"],
  "programme": "Learn to Row"
}

{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "url": "http://www.example.org/events/1",
  "name": "Rowing Class",
  "description": "A rowing class for beginners",
  "startDate": "2017-04-01T08:00:00",
  "duration": "PT60M",
  "level": ["Beginner"],
  "programme": {
    "name": "Learn to Row",
    "url": "https://www.britishrowing.org/go-rowing/learn-to-row/",
    "description": "Getting started in rowing couldn’t be easier!"
  }
}

{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "url": "http://www.example.org/events/1",
  "name": "Tai chi Class",
  "description": "A tai chi class intended for beginners",
  "duration": "PT60M",
  "eventSchedule": {
     "type": "Schedule",
     "startDate": "2017-01-01",
     "endDate": "2017-12-31",
     "frequency": "weekly",
     "byDay": "http://schema.org/Wednesday",
     "startTime": "19:00",
     "endTime": "20:00"
  }}

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

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

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

• a simple textual description
• a schema:PostalAddress
• a more fully defined schema:Place or one of its sub-types such as a schema:CivicStructure or schema:EventVenue

While all three forms are allowed by Schema.org, applications that publish opportunity data SHOULD either specify a schema:PostalAddress or a more detailed schema:Place description.

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

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

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

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

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

• 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://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]).

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

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.

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

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

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