Abstract

Opportunity data describes opportunities for people to be physically activity. The data includes events, the locations in which they take place and descriptions of the physical activities that will participants will engage in.

Opportunity data can be published as open data, for anyone to access use and share. This allows the data to be reused to create applications and services that can help people become more physically active.

The Openactive Community Group are developing standards to support the publication and reuse of opportunity data. This primer demonstrates how to use those standards to describe and publish a variety of different types of opportunity data.

Where possible, this primer links back to the relevant definitions in the underlying standards. Nothing in this primer overrides those normative definitions.

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 Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

The OpenActive Community Group was established with the objective of facilitating the sharing and use of physical activity data. The group has so far produced several specifications that contribute towards achieving this aim:

This document serves as a primer for developers to help them understand how to use those specifications to describe and publish different types of data.

If you wish to make comments regarding this document, please send them to [email protected] (subscribe, archives).

1. 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 word MAY is to be interpreted as described in [RFC2119].

This primer makes use of the compact IRI Syntax; please refer to the Compact IRIs from [JSON-LD].

The following namespaces are used in this primer:

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/

2. Typographical Conventions

The following typographic conventions are used in this primer:

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

3. Overview

3.1 What is opportunity data?

There are several different types of data that are relevant to describing physical activities.

Figure 1 Types of physical activity data

Opportunity data includes:

3.2 What formats can be used to publish opportunity data?

The Modelling Opportunity Data ([Modelling-Opportunity-Data]) specification has been designed to allow opportunity data to be published in a variety of formats. Data could be published as JSON, XML, RDF, or even CSV files.

It is expected that the most commonly used format will be JSON. All of the examples in this document use [JSON-LD] syntax. JSON-LD provides a means of publishing data as simple JSON documents but ensures that the terms used in the data are all linked to a standard, machine-readable definition.

This helps users of the data to be confident about the meaning of the individual fields in the data. This helps to simplify data integration.

3.3 What data standards are used to describe opportunity data?

There are three standards that have been used to help define a common data model for opportunity data. These are:

3.4 How can I validate my opportunity data?

Note

The OpenActive project and community group are planning to develop additional validation tools for developers. Links to those tools will be added in future drafts of this primer

Currently there are two tools that can help to validate opportunity data:

4. Describing Opportunity Data

The [Modelling-Opportunity-Data] specification defines a data model for opportunity data. The model provides a means for different platforms and applications to publish data in a consistent way. This makes it easier for users to work with data from multiple publishers.

The following sections each illustrate how a different aspect of the data model can be used to publish certain types of data.

Note

In the following sections all references to terms defined in other specifications have been qualified using their namespace prefix. This helps to highlight the source vocabulary in which they are defined. The terms are also linked to their definitions.

The examples in each section use [JSON-LD] syntax and make use of the terms declared in the OpenActive Vocabulary. This feature of [JSON-LD] removes the need to use explicit namespace prefixes.

4.1 How do you indicate that your data conforms to the specification?

It is important to indicate to users of your data that your data conforms to the [Modelling-Opportunity-Data] specification. This is achieving by:

A JSON-LD context maps the terms used in a JSON document to their standard definitions. To indicate that your data conforms to the [Modelling-Opportunity-Data] specification, include a @context reference that refers to our JSON-LD context:

Example 2: Adding a context
{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  ...include rest of data here...
}

4.2 Describing Events

The following sections illustrate different aspects of describing Events. For more information consult the Describing Events section of the data model.

4.2.1 How do you describe an session?

The basic information required about a session is

  • its name
  • a URL providing a link to a web page describing the session
  • the time at which the event will take place
  • an indication of the type of activity that will take place at an event
  • the location at which the event will take place

The following example illustrates this basic usage:

Example 3: Describing a session
{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "name": "Tai chi Class",
  "url": "http://www.example.org/events/1",
  "startDate": "2017-03-22T20:00:00",
  "activity": "Tai Chi",
  "location": {
    "type": "Place",
    "name": "ExampleCo Gym",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "1 High Street",
      "addressLocality": "Bristol",
      "postalCode": "BS1 4SD"
    }
  }
}

The type property indicates that the JSON is describing an Event rather than one of the other types of resource defined in the data model.

This is a very basic session description. The following sections in this primer illustrate how to provide more detail.

4.2.2 How do you describe when a session will take place?

The example in the previous section illustrated how to the the schema:startDate property to specify the starte time of an event. The property value must be an [ISO8601] date or date time.

It would be useful for participants to also how long the session will last. The schema:endDate and schema:duration properties allow this to be defined in two different ways.

Example 4: Describing a session
{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "name": "Tai chi Class",
  "url": "http://www.example.org/events/1",
  "startDate": "2017-03-22T20:00:00",
  "endDate": "2017-03-22T21:00:00",
  "duration": "PT60M",
  "activity": "Tai Chi",
  "location": {
    "type": "Place",
    "name": "ExampleCo Gym",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "1 High Street",
      "addressLocality": "Bristol",
      "postalCode": "BS1 4SD"
    }
  }
}

Adding an schema:endDate allows you to specify the exact end time of the session. The schema:duration allows the length of the session to be defined using an [ISO8601] duration.

While the duration can be calculated from a start and end time, or an end time from a start time and a duration, there are options to use both to convey more information.

For example if an data publisher includes both a start time AND an end time, then the duration property MAY be used to specify the actual length of the activity.

In the following example a gym class begins at 6pm and ends at 7pm. But the event involves a ten minute setup and tear down at the beginning and end of the session. In this case the duration of the activity is actually 40 minutes:

Example 5: Using duration to illustrate length of activity
{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "name": "Gym Class",
  "url": "http://www.example.org/events/1",
  "startDate": "2017-03-22T18:00:00",
  "endDate": "2017-03-22T19:00:00",
  "duration": "PT40M",
  "activity": "Gymnastics",
  "location": {
    "type": "Place",
    "name": "ExampleCo Gym",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "1 High Street",
      "addressLocality": "Bristol",
      "postalCode": "BS1 4SD"
    }
  }
}

4.2.3 How can you provide a description of an event?

The schema:description property can be used to provide a short description of an event.

Example 6: Describing a session
{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "name": "Tai chi Class",
  "description": "A tutored beginner's class that will involve demonstrates and a set of warm-up activities. Everyone welcome",
  "url": "http://www.example.org/events/1",
  "startDate": "2017-03-22T20:00:00",
  "activity": "Tai Chi",
  "location": {
    "type": "Place",
    "name": "ExampleCo Gym",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "1 High Street",
      "addressLocality": "Bristol",
      "postalCode": "BS1 4SD"
    }
  }
}

The description should be an overview of the event that provides more detail to attendees. The content may be reused in a number of different contexts, e.g. web and mobile applications. For this reason it should ideally not include any HTML markup, although applications MAY include markup, e.g. to link to additional material.

4.2.4 What information is useful to include in a session description?

The schema:description field supports event organisers in providing a free-text description of their event. A good Event description will include sufficient detail that will help participants understand what the event will involve. For example it might be useful to include:

  • a description of how the event will be run
  • the types of people who are or will be attending the event
  • information on the event organiser
  • notes on any equipment required
  • suggested apparel, e.g. footwear, kit, etc

The [Modelling-Opportunity-Data] specification provides additional ways to describe events using more structured data. This includes:

  • providing photos of an event, so participants can see what might be involved
  • adding categories to describe an event, e.g. its intensity
  • describing the suitability of an event for different types of participants
  • information on the format of an event, e.g. does it follow a branded programme?
  • adding descriptions of the event organisers and any contributors involved in running the event

The following sections cover those aspects in more detail.

4.2.5 How do you describe the physical activities take will place during a session?

The physical activity that will take place at an event are described using the oa:activity property:

Example 7: Adding an activity
{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "name": "Tai chi Class",
  "activity": "Tai Chi",
}

The name of the activity is provided as the value for the property. Applications may allow event organisers to enter their own activity names or instead require them to select names from a standard list of activities.

Note

The OpenActive Community Group are working on a roadmap to develop a standardised list of activities for the sector. In addition to this, organisers that are already curating activity lists are encouraged to publish them as open data.

4.2.6 What if a session will involve multiple activities?

The value of oa:activity property can be a list of activity names, specified as a JSON array in the following example:

Example 8: Adding multiple activities
{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "name": "General fitness class",
  "activity": ["Aerobics", "Weight Lifting", "Yoga"]
}

4.2.7 How can you refer to activities from a standard activity list?

The Physical Activities used to describe an event may be drawn from a standard Activity List.

In this case it is useful to make this explicit in the opportunity data. In the following example the Physical Activity associated with the Event is expressed as a structured value (a JSON object). This allows more information to be provided, including not just its name, but also its identifier, and the identifier of the Activity List from which it has been drawn:

Example 9: 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": "http://example.org/activity-list#tai-chi",
    "type": "Concept",
    "prefLabel": "Tai chi",
    "altLabel": "Tai-chi",
    "inScheme": "http://example.org/activity-list"
  }
}

An application that uses this data may then access the activity list to find out more information about the event. For example whether there are broader terms (e.g. "Martial Arts" or "Combat") that could be used to drive discovery and recommendations of events to potential participants.

4.2.8 How can you add a programme to an event?

Events are often organised and run in a variety of ways. These different formats are often associated with specific branding, e.g. "Les Mills BodyPump" or "Back to Netball". These are referred to a Programmes in the [Modelling-Opportunity-Data] specification.

Events can be associated with a Programme using the oa:programme property. In its simplest form this allows the name of a Programme be provided as part of the event description:

Example 10: Adding a Programme
{
  "@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"
  "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 11: Supplying more information about a Programme
{
  "@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",
  "category": ["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!"
  }
}

4.2.9 How can you describe suitability of events?

There are a variety of ways of expressing that an Event is suitable for specific audiences. This includes describing that an event is:

  • suited for a specific age range
  • suited for people within a specific height or weight rage
  • restricted to a male, female or mixed audience

The following example illustrates how to indicate that an event it targeted as a specific age range (over 60s) but is open to a mixed audience:

Example 12: Age and gender example
{
  "@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"
}

An Event involving a climbing activity might be limited to people within a specific age or weight range. The following example describes na event that is suitable for anyone who are 10 or over, but expresses specific height and weight ranges:

Example 13: Age and gender example
{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "url": "http://www.example.org/events/1",
  "name": "Climbing adventure",
  "description": "A tree top climbing adventure",
  "startDate": "2017-03-22T10:00:00",
  "duration": "PT60M",
  "ageRange": "10",
  "genderRestriction": "mixed"
  "heightRange": "1.4",
  "weightRange": "45-125"
}

4.2.10 How are organisers described?

The organisers of an event might be an organisation such as a club, or it might be an individual trainer. Both of these can be described using terms from the specification.

The following example illustrates how to describe that the organiser of an event is a club (a schema:Organization):

Example 14: 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"  }
  
}

People can be described using the schema:Person type and then associated with an event as either an organiser (as above) or a contributor. The contributor property allows individual trainers or instructors to be associated with an event alongside an organiser

Example 15: Adding a trainer
{
  "@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"  }
  
  "contributor": {
    "type": "Person",
    "name": "John Smith",
    "description": "Experienced Tai chi instructor with 10 years of experience"  }
  
}
Note

Applications should not publish personal data without permission

However applications should 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 should not be published as open data without getting the consent of the individual concerned.

oa:category
Example 16: 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": ["Beginner", "Low intensity"]
}

4.2.11 How do you add a location to an event?

Locations are added to events using the schema:location property. The recommendation in the [Modelling-Opportunity-Data] specification is that applications should provide as much information about the Place in which the event will take place as possible. For example, the name and address for the venue:

Example 17: Adding a location
{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "name": "Tai chi Class",
  "url": "http://www.example.org/events/1",
  "startDate": "2017-03-22T20:00:00",
  "activity": "Tai Chi",
  
  "location": {
    "type": "Place",
    "name": "ExampleCo Gym",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "1 High Street",
      "addressLocality": "Bristol",
      "postalCode": "BS1 4SD"
    }
  }
  
}

The specification provides some flexibility to accommodate the variety of ways that systems index and collect location information. For example it is permitted to only specify an address for a location:

Example 18: Adding an address
{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "name": "Tai chi Class",
  "url": "http://www.example.org/events/1",
  "startDate": "2017-03-22T20:00:00",
  "activity": "Tai Chi",
  
  "location": {
    "type": "PostalAddress",
    "streetAddress": "1 High Street",
    "addressLocality": "Bristol",
    "postalCode": "BS1 4SD"
  }
  
}

The location property can also be used to provide just the name of a location, e.g. "Bath Leisure Centre".

However this means that participants have less information about where the event will be running. Applications should instead include a more complete Place description as described in the following section.

4.2.12 How are recurring events described?

Note

This section is contingent on an open issue so may be subsequent to change. There is a discussion under way in the Schema.org community to extend their model to cover recurring events. The proposal is to add a new schema:eventSchedule property that will refer to a recurrence rule as defined in the iCalendar specification. The assumption is that this proposal will be expected and the specification will then recommend use of the schema:eventSchedule property. The following section is written on that basis but is subsequent to change.

Some systems allow organisers to set up a schedule of events. The [Modelling-Opportunity-Data] specification allows these schedules to be shared as open data, as well as Events that occur at a specific date and time. Sharing those events allows aggregators to more efficiently collect data on events, rather harvesting (potentially endless) lists of individual events.

The following example illustrates basic usage of the proposed schema:eventSchedule property. The data describes a Tai Chi class that occurs every Wednesday at 7pm:

Example 19: 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",
     "frequency": "weekly",
     "byDay": "http://schema.org/Wednesday",
     "startTime": "19:00",
     "endTime": "20:00"
  }}

4.3 Describing Locations and Facilities

The following sections provide examples of describing the Places in which events take place, using the location aspects of the data model.

4.3.1 How do you add a geographic location?

The section on adding a location to an event introduces the basic uses of the schema:location property. In addition to providing an address, some systems may also hold the geographic coordinates of a location.

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"
  },
  
  "geo": {
    "latitude": "51.3816123",
    "longitude": "-2.3544367"
  }
  
}

4.3.2 How do you add contact details?

Contact details for a Place can be expressed using the schema:telephone and schema:faxNumber properties, as shown in the following example:

Example 21: Adding contact details to a Place
{
  "@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",
  "faxNumber": "+44 (0)1225 486906"  
}

The [Modelling-Opportunity-Data] specification doesn't provide support for providing contact details for an Event, although these could be provided to users as information about the event at its public URL.

Contact information is only currently supported for Place (as shown above) or for individual people or organisations, via the schema:contactPoint property.

4.3.3 How do you add opening times?

The opening times for a Place can be added using the schema:openingHoursSpecification property. This property refers to a structured value known as an schema:OpeningHoursSpecification.

The following example illustrates how to state that a leisure centre is open from 9am to 5pm every day of the week:

Example 22: Listing opening hours
{
  "@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"
  },
  
  "openingHoursSpecification": [
    {
      "@type": "OpeningHoursSpecification",
      "closes":  "17:00:00",
      "dayOfWeek": "http://schema.org/Sunday",
      "opens":  "09:00:00"
    },
    {
      "@type": "OpeningHoursSpecification",
      "closes": "17:00:00" ,
      "dayOfWeek": "http://schema.org/Saturday",
      "opens": "09:00:00"
    },
    {
      "@type": "OpeningHoursSpecification",
      "closes":  "17:00:00",
      "dayOfWeek": "http://schema.org/Thursday",
      "opens": "09:00:00"
    },
    {
      "@type": "OpeningHoursSpecification",
      "closes": "17:00:00",
      "dayOfWeek": "http://schema.org/Tuesday",
      "opens": "09:00:00"
    },
    {
      "@type": "OpeningHoursSpecification",
      "closes": "17:00:00",
      "dayOfWeek":  "http://schema.org/Friday",
      "opens": "09:00:00"
    },
    {
      "@type": "OpeningHoursSpecification",
      "closes": "17:00:00",
      "dayOfWeek": "http://schema.org/Monday",
      "opens": "09:00:00"
    },
    {
      "@type": "OpeningHoursSpecification",
      "closes": "17:00:00",
      "dayOfWeek":  "http://schema.org/Wednesday",
      "opens": "09:00:00"
    }
  ]}
  
}

In the above example the property value is an array of opening times.

The Schema.org definition of schema:OpeningHoursSpecification includes more detail and examples of its usage.

4.3.4 How do you describe the facilities at a location?

A Place, such as a Leisure Centre, might include facilities such as a football pitch, swimming pool, etc. To help distinguish between a Place and a facility, Schema.org defines some additional types, e.g. a CivicStructure or a SportsActivityLocation.

The relationship between a Place and its facilities can be expressed using the containment properties (schema:containedInPlace and schema:containsPlace).

The following example shows how to describe that a Leisure Centre includes a gym. Note that the gym has a different type:

Example 23: Describing facilities at 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"
  }
  }

This allows Events to be associated with a more specific location within a larger venue. In the following example, a Tai Chi class is described as occuring in a Sports Hall within a Leisure Centre:

Example 24: Associating an event with a facility in a venue
{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "name": "Tai chi Class",
  "url": "http://www.example.org/events/1",
  "startDate": "2017-03-22T20:00:00",
  "activity": "Tai Chi",
  "location": {
    "type": "SportsActivityLocation",
    "name": "Main Sports Hall",
    "containedIn": {
      "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"
      }
    }
  }

}

Because a facility is treated as a Place, it can be described using the other properties shown elsewhere in this primer. So, for example the gym may have different opening hours to the rest of the leisure centre.

4.3.5 How do you describe walking trails and other opportunities at a location?

Not all opportunities to be physically activity are organised Events. Some opportunities are self-directed for example walking routes or mountain bike trails. These are referred to as Activity Opportunities.

The data model explains that these types of opportunity are similar to events except:

  • they have a specific type, oa:ActivityOpportunity
  • do not have a schedule, start or end time (but may have a duration)

The following example describes a 4 hour walking trail around Bath organised by the National Trust:

Example 25: Descring a walking trail
{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "ActivityOpportunity",
  "name": "Bath Skyline Walk",
  "description": "Savour the magnificent views down into the picturesque World Heritage City of Bath on our most popular walking trail",
  "url": "https://www.nationaltrust.org.uk/bath-skyline/trails/bath-skyline-walk",
  "duration": "PT4H",
  "activity": "Walking",  "category": ["Moderate", "Dog-friendly"],
  "image": "https://www.nationaltrust.org.uk/images/1431731033620-mapbathskyline.jpg",
  "location": {
    "type": "Place",
    "name": "Bathwick Hill",
    "geo": {
      "latitude": "51.380837",
      "longitude": "-2.3462374"
    }
  },
  "organiser": {
    "type": "Organization",
    "name": "National Trust"
  }

}

4.4 Describing Activity Lists

This section describes how to publish data about Physical Activities using described using SKOS

4.4.1 Describing a simple list of activities

An Activity List provides descriptions of physical activities. The simplest form of activity list is just a list of activity names as shown below:

Example 26: A simple activity list
{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "ConceptScheme",
  "url": "http://www.example.org/activity-list",
  "title": "Example Activity List",
  "description": "An example activity list",
  "concepts": [{
    "type": "Concept",
    "prefLabel": "Karate",
  }, {
    "type": "Concept",
    "prefLabel": "Tai Chi",
  }]
}

An Activity List should have a title, a description and a list of concepts. Each concept in the list should have a skos:prefLabel that provides the canonical name for the activity.

When publishing an activity list it should also have a licence that describes how the list can be used. This is described in Publshing Activity Lists as open data

4.4.2 Adding alternate names for an activity

There may be several ways to refer to a physical activity. This includes alternate names or spellings of the activity. Providing these alternative labels can help applications create better user interfaces by guiding them towards using a standard set of activity names.

The following example shows how to add an skos:altLabel property to an activity. In this case a simple spelling variant:

Example 27: Adding an alternative name for an activity
{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "ConceptScheme",
  "url": "http://www.example.org/activity-list",
  "title": "Example Activity List",
  "description": "An example activity list",
  "concepts": [{
    "type": "Concept",
    "prefLabel": "Tai Chi",
    "altLabel": "Tai-chi"
  }]
}

Any number of alternative labels can be added to an activity by providing a list of values:

Example 28: Adding multiple names for an activity
{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "ConceptScheme",
  "url": "http://www.example.org/activity-list",
  "title": "Example Activity List",
  "description": "An example activity list",
  "concepts": [{
    "type": "Concept",
    "prefLabel": "Tai Chi",
    "altLabel": ["Tai-chi", "Tai Chi Chuan"]
  }]
}

4.4.3 Describing hierarchical lists of activities

More complex activity lists describe a hierarchy of physical activities. For example Judo, Karate and Kendo are all examples of a broader category of Martial Arts. This is demonstrated in the following example:

Example 29: Describing a hierarchical 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": "Judo"
    },
    {
      "type": "Concept",
      "prefLabel": "Kendo"
    },
    {
      "type": "Concept",
      "prefLabel": "Karate"
    }]  }]
}

5. Publishing opportunity data

This section provides some advice on how to publish opportunity data for others to reuse.

5.1 How can activity lists be published using JSON-LD?

Activity Lists can be published as open data by publishing a JSON-LD file that developers can download and use within their application.

The data could be added as a download that is made available from an "open data" page on your organisations website.

Ensure that the activity list has a license property that refers to a standard open data licence so that users can be certain that they have rights to use the data.

5.2 How can session data be published via an API?

The Realtime Paged Data Exchange specification defines an API that allows opportunity data to be published in a way that can be easily harvested by reusers.

The API does not define how opportunity data should be structured. It only defines a generic data structure which can accept any JSON object.

That object can conform to the JSON-LD structure described in this primer.

For more detail, consult the OpenActive website which provides more documentation on the process of opening your data using this API.

5.3 How can opportunity data be embedded in web pages?

Opportunity data can be embedded in web pages to make it acccessible to search engines and similar web crawlers. JSON-LD can be embedded in web pages using a script tag with a type of application/ld+json:

Example 30: Embedding JSON
<script type="application/ld+json">
{
  "@context": "https://www.openactive.io/ns/oa.jsonld",
  "type": "Event",
  "name": "Tai chi Class",
  "url": "http://www.example.org/events/1",
  "startDate": "2017-03-22T20:00:00",
  "activity": "Tai Chi",
  "location": {
    "type": "Place",
    "name": "ExampleCo Gym",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "1 High Street",
      "addressLocality": "Bristol",
      "postalCode": "BS1 4SD"
    }
  }
}
</script> 


Using this method a machine-readable description of an Event can be directly included within the web page for the event.

A. Acknowledgements

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

B. References

B.1 Normative references

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

B.2 Informative references

[ISO8601]
Representation of dates and times. ISO 8601:2004.. International Organization for Standardization (ISO). 2004. ISO 8601:2004. URL: http://www.iso.org/iso/catalogue_detail?csnumber=40874
[JSON-LD]
JSON-LD 1.0. W3C. W3C Recommendation. URL: https://www.w3.org/TR/json-ld/
[Modelling-Opportunity-Data]
Modelling Opportunity Data. Open Active Community Group. CG-DRAFT. URL: https://www.openactive.io/modelling-opportunity-data/
[OpenActive-Vocabulary]
OpenActive Vocabulary. Open Active Community Group. CG-DRAFT. URL: https://www.openactive.io/ns/
[Realtime-Paged-Data-Exchange]
Realtime Paged Data Exchange. Open Active Community Group. CG-DRAFT. URL: https://www.openactive.io/realtime-paged-data-exchange/
[SCHEMA-ORG]
Schema.org. URL: http://schema.org/
[SKOS]
SKOS Simple Knowledge Organization System Primer. W3C. W3C Note. URL: https://www.w3.org/TR/skos-primer