Route Guide Specification - 1.0 CR

Candidate Recommendation

Latest editor's draft:
Timothy Hill (Open Data Institute)
GitHub openactive/routes
File a bug
Commit history
Pull requests


This specification introduces a data model to support the publication of data describing paths and trails for recreational use. In broad terms it models the kind of information found in a guidebook or trail guide regarding the navigation, use, and enjoyment of recreational routes.

Within this and related documents, the paths, trails, and routes that form the subject of this information are referred to generically as Routes.

The specification is intended to support the publication of such data as open data for anyone to access, use and share. It will also guide reusers of this data, introducing them to the key concepts relevant to this domain.

Though it is not in itself a geo-representation standard, the model may prove useful in relation to applications with a geo focus, such as apps for routefinding and other kinds of navigation support and guidance.

The specification is an output of the OpenActive Community Group and serves as a common reference point for other specifications and outputs of that activity.

The data model introduced in this document has been mapped to existing standards and vocabularies, including SKOS ([SKOS]) and the ([SCHEMA-ORG]) types and properties. This existing work provides a useful existing framework around which the OpenActive Community Group can build additional data standards.

Status of This Document

This specification was published by the OpenActive Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

Contributions to this document are not only welcomed but are actively solicited and should be made via GitHub Issues and pull requests. The source code is available on GitHub.

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

1. Introduction

This section is non-normative.

The W3C OpenActive Community Group was established with the objective of facilitating the sharing and use of physical activity data. Open publishing of this data has enormous potential to increase participation in physical activities of all kinds. Within this larger concern, routes data occupies a distinctive place, often serving both as an opportunity for self-guided activity and as a site for directed group activities, such as e.g. foot- or bike-races, guided walks, or training routines.

1.1 Requirements

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

1.1.1 Support continuous curation

Very often, route data is developed incrementally: initially, a bare framework of information is provided, which subsequent users or authorities fill in over time or as part of an organised campaign. The specification thus contains very few REQUIRED fields, but a large number of RECOMMENDED ones, on the assumption that this can help to guide prioritisation of information collection.

1.1.2 Support a wide variety of route types

In the course of development, it has become apparent that the requirements for different kinds of routes vary greatly - in particular, urban and rural routes have very different profiles. The aim of this specification is to support all forms of non-motorised recreational route use. Thus, while it is unlikely that any one route will leverage all or even the majority of this specification's features, all should ultimately prove useful within the broad spectrum of existing route types.

1.1.3 Support a wide variety of users

The purpose of the OpenActive initiative is to increase participation in physical activity, particularly amongst those who are currently less active than they would like to be due to barriers of access or enjoyment. Issues of accessibility, safety, and amenities accordingly play an large role in the specification. Though it may be the case that few publishers can currently populate all accessibility and safety fields with sufficient data, the model is deliberately designed prospectively, to support rich modelling in these areas and guide future data-gathering (see 'continuous curation', above).

1.1.4 Be agnostic to formats and APIs

Reflecting the wide variety of tools and platforms in use, and also that the sector is at an early stage in sharing its data more widely, this specification does not prescribe specific data formats or APIs. Ideally opportunity data could be published as JSON, XML, CSV or other formats.

1.1.5 Create an extensible framework

This specification should support extensions to allow it to be customised and revised to meet future requirements, as well as the needs of specific communities of data publishers and consumers.

1.2 Scope

This specification defines a data model for information that gives a user guidance for navigation around and enjoyment of a geographic entity, a 'route'. As noted under the opening Abstract, it broadly models the kind of information typically found in a guidebook or pamphlet for a recreational trail, and does not attempt to model the route as a geographical entity per se.

The following items are therefore out of scope for this specification:

While RouteGuides may (and in most cases will) be associated with and point to files or representations that support advanced geo features, the RouteGuide standard itself does not; its purpose is enrichment and description of a geographic entity (a 'Route') rather than cartographic representation of this.

1.3 Relationship to other OpenActive standards

Many publishers of RouteGuides will have only this kind of data, and there is no barrier to publishing RouteGuides as standalone data objects in whatever format the publisher deems appropriate. However, for many use-cases data-publishers may find it useful to integrate their RouteGuide data with other OpenActive standards.

1.3.1 Realtime Paged Data Exchange (RPDE)

Generally, the most convenient form for publishing RouteGuide data will be as an RPDE feed. This is particularly true in cases where RouteGuide data is to be harvested alongside other OpenActive data and/or is frequently updated.

For further information, see the Realtime Paged Data Exchange 1.0 specification.

1.3.2 The Activity List

The OpenActive Activity List is a curated list of canonical identifiers for use across the physical activity sector. It is RECOMMENDED that data-publishers align their activity descriptions with this where appropriate. It is anticipated that the activities most relevant to RouteGuides will typically be:

Various sub-classes of these top-level concepts may also be appropriate.

1.3.3 Modelling Opportunity Data

In cases where a recreational route serves as the site of some planned group activity, this recreational route is best modelled using the routeGuide property of the Event class, as outlined in the current Modelling Opportunity DataEditors Draft.

The RouteGuide data object itself may be fully represented as the value of this property. Alternatively, it may be populated by a URL that resolves to such a data object.

1.3.4 The Booking API

Recreational routes are not normally 'bookable', in the sense that one must reserve access to them at a given time, place, and/or price. In cases where this functionality is required, the RouteGuide should normally be modelled as a property of an Event (or one of its subclasses), and the Event then be treated as the bookable entity.

Modelling booking can be complex. Readers with this use-case in mind are advised to consult both the Modelling Opportunities Data standard and the Open Booking API standard documentation in detail

1.4 Structure of this document

This specification is divided into three main sections:

  1. Introduction - provides a broad definition of Route Guide data and goals for this specification
  2. Data Model - a data model that maps the key concepts to some standard vocabularies
  3. Worked Example - in order to ground the specification and illustrate its application, an extensive worked example (The Avebury Archaeology Walk) is provided.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

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

3. Typographical Conventions

The following typographic conventions are used in this specification:

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

Notes are in light green boxes with a green left border and with a "Note" header in green. Notes are normative or informative depending on the whether they are in a normative or informative section, respectively.

Examples are in light khaki boxes, with khaki left border, and with a
numbered "Example" header in khaki. Examples are always informative.
The content of the example is in monospace font and may be syntax colored.
Advisements are used to highlight important normative statements, in particular best practices.

4. Data Model

The data model described in the following sections reuses existing standards and vocabularies which have then been extended to cover the additional requirements needs to support the publication of opportunity data.

The Simple Knowledge Organisation System ([SKOS]) is a W3C standard for publishing taxonomies and category schemes. It can be used to help publish and organise Activity Lists and to describe Physical Activities. [SCHEMA-ORG] provides an existing well-used and documented data model for publishing data to the web. It provides an existing model for describing Events, Organisations, People, and Places.

Both standards are widely used, and can be used to publish data in a variety of structured formats, including [JSON-LD].

This OpenActive Vocabulary [OpenActive-Vocabulary] is a custom vocabulary designed to support the publication of RouteGuide data. It defines a number of new terms that extend SKOS and to cover additional requirements highlighted in this specification.

Note that the fundamental object-type described in this document (RouteGuide) is itself a specialisation and extension of's CreativeWork type.

4.1 Namespaces

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


In the following sections all referenced terms have been qualified using their namespace prefix. This highlights the source vocabulary in which they have been defined. Terms have also been linked to their definitions.

The examples in each section use [JSON-LD] syntax and reference the [OpenActive JSON-LD context]( defined by [OpenActive-Vocabulary], which is accessible at when using an Accept header that includes application/ld+json.

The context removes the need to use explicit namespace prefixes in the JSON documents. The context also maps the JSON-LD [@type]( and [@id]( properties to simple keys (type and id). This further limits the amount of JSON-LD syntax exposed to developers.

4.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, and the OpenActive Vocabulary ([OpenActive-Vocabulary]).

Concept Mapping Notes
Activity List skos:ConceptScheme Activity lists are controlled vocabularies and map well to the definition of a SKOS Concept Scheme.
Physical Activity skos:Concept Individual Physical Activities can be represented as individual SKOS concepts
Place schema:Place As well as the general definition of a Place, defines sub-types including
Organization schema:Organization Covers all types of organisations, including companies, clubs, etc
Person schema:Person An individual person

4.3 Identifying and Linking Resources

This specification adopts the same approach as and encourages the use of URLs as unique identifiers for resources.

Where information about Events, Places, Organizations and other types of resource has already been published online, their existing URLs should be used as identifiers to avoid the need to create new identifier schemes.

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:

Warning: Route Guide property URLs in the oa: namespace currently do not resolve. Providing resolvable definitions is a work-in-progress to be completed 2020-02-14.

This specification provides three properties for identifying resources:

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

If applicable then publishers may choose to use the same URI for these two properties. If an @id property is not provided then applications MAY choose to rely on the value of 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.

Example 2: Simple route description

    "@context": "",
    "type": "RouteGuide",
    "id": "",
    "url": "",
    "name": "Avebury Archaeology Walk"

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

4.4 Publishing Route Guide Data

As noted above, it is possible (and in many cases desirable) to publish Route Guide data as an RPDE feed. In this case, the Route Guide will necessarily be expressed in JSON in a manner conformant to the RPDE specification.

However, the Route Guide specification is in itself format-agnostic. Route Guide data may be published through a variety of channels (downloaded in .zip file, embedded on a web-page, etc.) and in a variety of formats (JSON, XML, microformats, etc.). Considered in terms of the specification itself, the following two expressions are identical:

Example 3: Simple route description as JSON

    "@context": "",
    "@type": "RouteGuide",
    "@id": "",
    "url": "",
    "name": "Avebury Archaeology Walk"
Example 4: Simple route description as XML
<oa:RouteGuide xmlns:oa="" xmlns:schema="">
    <schema:name>Avebury Archaeology Walk</schema:name>

It is expected that data publishers will adopt whatever format best suits their use-case and supports their frequency of updating.

Note: Embedding RouteGuide JSON in an HTML 5 page

In cases where publication is as a JSON object within an HTML 5 page, it is RECOMMENDED that the object be encoded as the contents of a script element with a type value of application/json.


<script type="application/json" id="example"> { "@context": "", "@type": "RouteGuide", "@id": "", "url": "", "name": "Avebury Archaeology Walk" } </script>

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

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

4.7 Describing Route Guides (oa:RouteGuide)

The purpose of the Route Guide 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 Guides are often generated over an extended period of curation: that is to say, initially sparse information about a Route is augmented over time, until a full description of the Route emerges. While the Route Guide model is rich, then, the number of REQUIRED fields is relatively small, in keeping with this curation workflow.

Note that RouteGuide is a subclass of schema:CreativeWork. While any of the properties defined for CreativeWork are therefore available for use, the subset listed below, when complemented by the additional OpenActive (oa:)-defined properties provided, are proposed as those most applicable to RouteGuide modelling.

Property Status Type Notes
@type REQUIRED String RouteGuide
@id REQUIRED schema:url A URI providing a unique identifier for the resource
schema:name REQUIRED schema:Text The name of the Route
schema:url OPTIONAL schema:url A URL to a web page (or section of a page) describing the Route.
schema:author OPTIONAL Array of schema:Person or schema:Organization Individual(s) or group(s) responsible for creating the original Route Guide information
schema:datePublished RECOMMENDED schema:Date Date the Route Guide was originally published
schema:dateModified RECOMMENDED schema:Date or schema:DateTime Last point at which route information was added or edited.
oa:verificationRecord RECOMMENDED oa:VerificationRecord See below, Describing Route Verification.
schema:description REQUIRED schema:Text A free text description of the Route.
schema:headline OPTIONAL schema:Text A short summary of the Route, for use as a tagline or preview.
oa:activity REQUIRED Array of schema:URL Specifies one or more physical activities that will take place during an event. The activities should ideally be taken from an activity list. In the context of Route Guides, the activity specified will normally be one or more of ("cycling"), ("walking") ("running"), ("Horse riding"), or a narrower term within these.
oa:distance REQUIRED schema:QuantitativeValue Length of Route. Must include both number and unit.
oa:indicativeDuration RECOMMENDED Array of oa:IndicativeDuration See Describing Indicative Duration
oa:startPoint REQUIRED oa:RoutePoint On modelling values here, see below: Describing Route Points.
oa:endPoint OPTIONAL oa:RoutePoint REQUIRED if isLoop is 'false'. On modelling values here, see below: Describing Route Points.
oa:pointOfInterest OPTIONAL Array of oa:RoutePoint Noteworthy points along the Route. On modelling values here, see below: Describing Route Points.
oa:accessibiltyDescription RECOMMENDED Array of schema:Text e.g. 'wheelchair friendly', 'hearing loop'
oa:gradient RECOMMENDED oa:RouteGradient
oa:surface RECOMMENDED Array of schema:URL or schema:Text If a URL, MUST be drawn from,,,,,,, and
oa:routeDifficulty OPTIONAL Array of oa:RouteDifficulty Although typically only one RouteDiffulty is expected, Routes suitable for more than one kind of activity (e.g., walking and horse-riding) may require multiple values here.
oa:geoPath RECOMMENDED Array of schema:Map REQUIRED if no mapImage is provided. URL MUST resolve to a file in a format that natively supports geo encoding, e.g. geoJSON or GPX
oa:mapImage OPTIONAL Array of schema:Map REQUIRED if no geoPath is provided.
oa:category OPTIONAL Array of schema:Text or skos:Concept e.g. "pushchair-friendly", "family", "forest walk"
oa:additionalInformation OPTIONAL Array of schema:Article Historical, scientific, or any other information providing interesting background detail regarding the Route. If this information relates to a specific point or structure along the Route, it may be more appropriate to model this as a pointOfInterest.
schema:amenityFeature RECOMMENDED Array of schema:LocationFeatureSpecification e.g., “Parking”, “Toilets”. Where an amenityFeature may be modelled as a feature either of RouteGuide or of a RoutePoint, preference should be given to the RoutePoint (that is to say, to the more-specific level of modelling). For further guidance on modelling amenities, see Describing Amenities in the Opportunity Specification
oa:isLoop OPTIONAL Boolean Whether the route returns to its point of origin
oa:riskInformation RECOMMENDED oa:RouteRiskAdvisory
oa:legalAdvisory RECOMMENDED oa:RouteLegalAdvisory
oa:routeAccessRestriction OPTIONAL Array of oa:RouteAccessRestriction Restrictions on or obstacles to use of the route
oa:suggestedEquipment OPTIONAL Array of schema:Text Items users of the Route are advised to bring. For Routes intended for novice use, advice on footwear, bicycle frame, etc. may not be out of place here.
schema:image OPTIONAL Array of schema:ImageObject Images of the Route.
schema:review OPTIONAL Array of schema:Review User-submitted ratings of the Route.
schema:contactPoint OPTIONAL schema:ContactPoint Contact details specifically related to the Route.
oa:userContributedContent OPTIONAL Array of schema:CreativeWork Links to user-generated content, such as e.g. images or descriptions of the Route, video or path-recordings of their traversal of the Route, etc. If this field is populated, it is recommended that the data-publisher have some means of filtering and otherwise curating user-generated content prior to publication.
schema:isBasedOn OPTIONAL Array of oa:RouteGuide See Describing RouteGuide Provenance, below.
oa:isJoinableThroughoutLength OPTIONAL schema:Boolean Indicates whether or not it is possible to join the Route at every point along its length - for instance, as in most urban streets and roads. In cases where joining the Route is only possible at selected points (as for instance in many rural Routes with restricted public thoroughfares), these should be modelled using RoutePoints. Defaults to false.
oa:segments OPTIONAL Array of oa:RouteSegmentGuide See Segmenting Routes
oa:segmentGroups OPTIONAL Array of oa:RouteSegmentGroup See Grouping Route Segments

4.7.1 Describing Maps: oa:geoPath and oa:mapImage

Cartographic representations of Routes ('maps', in common parlance) are typically provided in one of two format families: properly geographic format types, such as GeoJSON or the .osm format, which support sophisticated geo-specific functionality such as distance calculation or route-tracking; and simple images, such as .jpg files, which provide a visual overview of the relevant area but do not offer any further functionality.

The first kind of map should populate the oa:geoPath property; for the second, the oa:mapImage property should be used. In both cases, the relevant maps are modelled using the Map class. However, the data-profile of these Maps will differ slightly. oa:geoPath
Property Status Type Notes
@type REQUIRED String "Map"
schema:mapType OPTIONAL A MapCategoryType or OpenActive enumeration value (see 'Notes') May be taken from the MapCategoryType values defined by; alternatively,,, or may be used. If more than one Map value is provided for oa:geoPath, this property is REQUIRED for each Map
schema:url REQUIRED schema:URL A link to the file containing the map.
schema:encodingFormat REQUIRED schema:Text or schema:URL The MIME format of the associated file. oa:mapImage
Property Status Type Notes
@type REQUIRED String "Map"
schema:mapType OPTIONAL A mapCategoryType enumeration (though see 'Notes') May be taken from the MapCategoryType values defined by; alternatively,,, and may be used. If more than one Map value is provided for oa:geoPath, this property is REQUIRED for each Map
schema:image REQUIRED schema:URL A link to the image file depicting the map.
schema:encodingFormat REQUIRED schema:Text or schema:URL The MIME format of the associated file.

4.7.2 Describing Route Points: Start, End, and Of Interest (oa:RoutePoint)

Routes are typically characterised by a number of points of special significance along their path. At a minimum, a looping Route will requires at least a single startPoint to be usable. Often, however, Routes will also have an endPoint and sometimes various other pointsOfInterest along the way.

Such points, for the purpose of describing Routes, are a specialisation and extension of's Place type. While all properties defined for schema:Place are thus available to implementers, those listed below are considered to be most applicable to RouteGuides.

Property Status Type Notes
@type REQUIRED String "RoutePoint"
schema:name OPTIONAL schema:Text
schema:geo OPTIONAL schema:GeoCoordinates The geographic co-ordinates, specified as a latitude and longitude of a Place
oa:isAccessPoint OPTIONAL schema:Boolean Whether or not it is possible to join the Route as a whole at this point.
oa:isRecommendedAccessPoint OPTIONAL schema:Boolean Whether or not it is recommended to join the Route as a whole at this point, because of e.g. particular amentities at this point, or because the RouteGuide has been specifically tailored to facilitate this particular experience of it. On RouteGuide startPoint and endPoint attributes this defaults to true; otherwise it defaults to false.
oa:mapReference OPTIONAL Array of oa:MapReference
oa:transportNote OPTIONAL Array of oa:TransportNote Information about how to reach the RoutePoint.
schema:headline OPTIONAL schema:Text A short summary of the Route, for use as a tagline or preview.
schema:description REQUIRED schema:Text A free text description of the Route.
schema:amenityFeature RECOMMENDED Array of schema:LocationFeatureSpecification Used to indicate whether specific amenities are available at a location. The value of this property will be an array of schema:LocationFeatureSpecification objects, though for further information see "Describing Amenities" in the Modelling Opportunity Data specification.
oa:userContributedContent OPTIONAL Array of schema:CreativeWork Links to user-generated content, such as e.g. images or descriptions of the Route, video or path-recordings of their traversal of the Route, etc. If this field is populated, it is recommended that the data-publisher have some means of filtering and otherwise curating user-generated content prior to publication.
schema:sameAs OPTIONAL schema:URL URL of a reference Web page that unambiguously indicates the Place's identity. E.g. the URL of the item's Wikipedia page, Wikidata entry, or official website.

4.7.3 Describing Map References (oa:MapReference)

An oa:MapReference is simply a geographic reference specified in terms of some widely-used map or series of maps. In the UK, for instance, the Ordnance Survey Explorer and Landranger maps are frequently used to indicate the boundaries within which a geographic entity falls.

Property Status Type Notes
@type REQUIRED String "MapReference"
schema:publisher REQUIRED schema:Organization or schema:Person
oa:mapSeries OPTIONAL schema:Text e.g. 'Explorer', 'Landranger'
oa:mapNumber OPTIONAL schema:Text REQUIRED if no gridReference supplied
oa:gridReference OPTIONAL schema:Text REQUIRED if no mapNumber supplied

4.7.4 Describing Route Gradients (oa:RouteGradient)

An oa:RouteGradient captures the steepness of climb and descent along a Route. Data providers should bear in mind that many descriptors of gradient are mathematical and/or unstandardised in nature (e.g., when specified in terms of percentages), and may convey little to novice users. The provision of a gradient description is therefore RECOMMENDED.

In addition, gradient is often used as a component in, or proxy for, description of the difficulty of completing a given Route. Data publishers should therefore give careful thought as to whether their gradient information is better captured using the RouteGradient or RouteDifficulty models.

It is important that the gradient information conveyed by the RouteGradient object should apply to the entirety of the Route or Route Segment to which it is attached; that is to say, for instance, that gradient averages and total elevation gains and losses MUST be calculated across the entire length of the relevant Route or Route Segment in order to be useful. Where this is not the case, gradient data should either be omitted (as misleading) or additional Route Segments should be created, scoped strictly to the applicability of the gradient data.

Property Status Type Notes
@type REQUIRED String "RouteGradient"
oa:maxGradient RECOMMENDED schema:Text e.g. "7.5%", "4.2°"
oa:avgGradient RECOMMENDED schema:Text
oa:totalElevationGain OPTIONAL Integer Unit is metres.
oa:totalElevationLoss OPTIONAL Integer Unit is metres.
oa:gradientTerm OPTIONAL Array of schema:Text e.g. "Easy", "Moderate", "3"
oa:gradientDefinitionURL OPTIONAL schema:URL This will typically be a link to a page describing the meaning of the gradientTerm in more detail.
schema:description RECOMMENDED schema:Text

4.7.5 Describing Transport to and from the Route (oa:TransportNote)

Property Status Type Notes
@type REQUIRED String "TransportNote"
oa:transportMode REQUIRED schema:Text It is RECOMMENDED that the value of oa:transportMode be taken from the following list:,,,, or
schema:description REQUIRED schema:Text Instructions for navigation to the destination by means of the oa:transportMode

4.7.6 Describing Route Difficulty (oa:RouteDifficulty)

The oa:RouteDifficulty model describes the effort and level of fitness required to successfully complete a Route. Such assessments necessarily contain a strong subjective component, and data publishers are therefore encouraged to use the schema:description field to ground their assessment in more concrete terms such as oa:distance, oa:gradient, or oa:indicativeDuration, and/or to provide a difficultyDefinitionURL further explaining the rationale behind their assessment of difficulty. In addition, values provided in oa:category (such as e.g. 'pushchair-friendly') may provide valuable additional context.

Difficulty Level and Novice Users
Data publishers are advised that prospective Route users - and in particular novice or beginning walkers - often have difficulty assessing the degree of challenge involved in traversing a Route, either being readily discouraged from Routes they are in fact capable of or, more rarely, finding themselves exhausted or lost in the midst of difficult Routes they are as yet unprepared for. Publishers are accordingly recommended to devote care and attention to the difficulty information they provide, in particular to articulating the significance of the different components (gradient, distance, conditions, etc.) involved in accurately conveying difficulty.
Property Status Type Notes
@type REQUIRED String "RouteDifficulty"
oa:difficultyTerm OPTIONAL schema:Text e.g., 'Easy', 'Strenuous'. If this value is taken from a controlled vocabulary, a oa:difficultyDefinitionURL SHOULD be provided pointing to the definition of these terms.
oa:activity OPTIONAL skos:Concept]( Specifies the physical activity for which the oa:RouteDifficulty is relevant. This activity SHOULD ideally be taken from an activity list.
schema:description OPTIONAL schema:Text
oa:difficultyDefinitionURL OPTIONAL schema:URL e.g.

4.7.8 Describing Indicative Durations (oa:IndicativeDuration)

Being able to complete a Route within a given period is important to many users, particularly those who engage infrequently in outdoor activities because they feel pressed for time. While there is considerable variance in individual activity speed, a rough indication of how much time to allow is valued information for many users.

Property Status Type Notes
@type REQUIRED String "IndicativeDuration"
oa:activity REQUIRED skos:Concept Specifies the physical activity for which the schema:duration is relevant. This activity SHOULD ideally be taken from an activity list.
schema:duration REQUIRED String The duration of the event given in [ISO8601] format. Durations MUST NOT be zero length.

4.7.9 Describing Route Designations (oa:RouteDesignation)

An oa:RouteDesignation is a formal, legal declaration of the status of a given Route or Route Segment. As such, any given jurisdiction will define only a finite (usually quite small) number of possible Designations.

Property Status Type Notes
@type REQUIRED String "RouteDesignation"
oa:routeDesignationTerm REQUIRED Array of schema:Text See Example below
schema:description OPTIONAL schema:Text
schema:url OPTIONAL schema:URL
Example: Route Designations in the UK

In the UK, the number of legal statuses a Route might have is quite small, and all Routes will therefore be some assortment of:

  • Footpath
  • Bridleway
  • Byway Open to All Traffic
  • Restricted Byway
  • Recreational Route
  • National Trail
  • Highway Cycle Route
  • Other Public Access Route
  • Permissive Footpath
  • Permissive Bridleway
  • Traffic-free Cycle Route
  • National Cycle Network
  • Danger Area
  • Managed Access
  • Open Access Land
  • Right To Roam

The routeDesignationTerm field is reserved for strictly-defined terms such as these, and the RouteDesignation description property is then intended to hold a formal, legal definition of this routeDesignationTerm: for example,

Restricted byway – on these routes there are restrictions on how you can travel the route. You are permitted to use the route on foot, horseback, bicycle or horse drawn carriage. You cannot use any motorised vehicles along this route.

The url property is intended to hold a link resolving to a definition or further explanation of this term: see for instance

4.7.10 Describing Route Risk Advisories (oa:RouteRiskAdvisory)

The purpose of the oa:RouteRiskAdvisory model is to describe risks in sufficient detail that users are able to weigh these and feel they are making an adequately-informed choice when deciding to avail themselves of a Route.

Because the range of risks users may be concerned with is wide, including such disparate topics as personal threat, environmental factors, and shared use of Routes with other traffic; because individuals vary widely in the degree of risk they are prepared to tolerate; and because perceptions of risk involve a subjective component the oa:RouteRiskAdvisory model is intentionally eclectic and captures information in a variety of styles.


While modelling risk is challenging, user research also indicates it is a paramount concern, particularly amongst those who are inexperienced with or hesitant to engage in outdoor activities. Data publishers are RECOMMENDED to provide any and all risk information they can.

To avoid potential confusion between absence of risk information and absence of risk, in cases where no risk information is available it is RECOMMENDED that publishers indicate this explicitly.

Property Status Type Notes
@type REQUIRED String "RouteRiskAdvisory"
oa:knownRisks OPTIONAL Array of schema:Text e.g., "crime incidence","harrassment reported", "shared with heavy traffic"
oa:riskModifiers OPTIONAL Array of schema:Text Contextual factors influencing knownRisks, e.g. "time of day", "season"
oa:riskMitigators OPTIONAL Array of schema:Text Contextual factors reducing knownRisks, e.g. "guardrails provided", "well-lit"
oa:riskDescription RECOMMENDED schema:Text
oa:userSafetyFeedback OPTIONAL schema:Review
oa:isMaintained OPTIONAL Boolean Indicates whether the Route is actively maintained by e.g. a landowner or charitable organisation. Typically does not apply to urban Routes.
oa:isMaintainedBy OPTIONAL schema:Person or schema:Organization The Organization or or Person responsible for maintaining the Route. MUST NOT have a value if isMaintained is 'false'.
oa:riskInformationURL OPTIONAL schema:URL Should point to a formal definition outlining risk and mitigating factors, e.g.
oa:trafficDescription OPTIONAL schema:Text

4.7.11 Describing Route Restrictions (oa:RouteAccessRestriction)

Route Access Restrictions convey information regardihg restrictions on use or access to the Route that arising from reasons other than legal status, e.g., social convention, wildlife protection, or seasonal factors.

Property Status Type Notes
@type REQUIRED String "RouteAccessRestriction"
oa:routeAccessRestrictionTerm OPTIONAL Array of schema:Text e.g. "Routine maintenance", "Closed in deer mating season", "Dogs not allowed"
schema:description RECOMMENDED schema:Text
oa:routeAccessRestrictionInformationURL OPTIONAL schema:URL Should point to further advice about the restriction, e.g.
oa:routeAccessRestrictionTimeSpan OPTIONAL schema:Text Brief text indicating when the pragmaticRestriction applies, e.g, "Winter", "2020-01-01 to 2020-03-31"

4.7.12 Describing Route Verification (oa:VerificationRecord)

Because the condition and maintenance status of Routes can change over time, it is important where possible to provide information about the currency of Route information.

Property Status Type Notes
oa:verifiedBy REQUIRED Array of schema:Person or schema:Organization Person or organisation who has confirmed accuracy of Route information
oa:dateVerified REQUIRED schema:Date or schema:DateTime The most recent date upon which accuracy of Route information was verified by the schema:Person or schema:Organization responsible.

4.7.13 Segmenting Routes: Routes as a collection of sub-Routes

In practice, Routes are often broken down into a series of smaller units - so that, for instance, a scenic walk may be described in terms of traversals to various landmarks, or a multi-day cycle tour broken down into individual day or half-day progressions. These smaller units are here referred to as Route Segments, and they are described by Route Segment Guide.

Route Segment Guides are treated, for the purposes of this specification, as essentially identical to Route Guides: that is to say, they are themselves simply small Route Guides that happen to fall in a particular sequence and thereby comprise a larger whole.

Route Segment Guides, then, are identical to Route Guides, with the following exceptions:

  1. The presence of a sequence attribute. The value of this attribute MUST be an integer, and the values of the sequence attribute MUST run consecutively for the Route Segments comprising a Route.

  2. The availability of an OPTIONAL alternativeSegmentTo attribute, in cases where the end user has two alternative Route Segments or series thereof (e.g., a short and steep Segment alongside a longer, more leisurely, alternative) to complete their journey.

  3. Segments MUST NOT themselves contains Segments. That is to say, the segments attribute is FORBIDDEN for Route Segment Guides.

  4. Because the parent Route Guide can be assumed to convey the necessary information to users, all attributes are OPTIONAL for Route Segment Guides, even those that marked as REQUIRED for Route Guides.

In addition, the following structural constraints apply:

  1. If a Route contains Route Segments at all, it must contain AT LEAST two Segments. That is to say, a Route cannot consist of only a single Segment.

  2. If a Route contains Route Segments at all, these Segments MUST describe the entirety of the Route: there MUST NOT be any 'gaps' left unaccounted for by the Segments.

Property Status Type Notes
@type REQUIRED "RouteSegmentGuide"
oa:sequence RECOMMENDED Integer Indicates the presentation order of Route Segments within the parent Route. This ordering should normally be present, except for unusual situations such as e.g., modelling RouteGuides that are otherwise unsegmented but for access points. In cases where RouteSegmentGroups are provided, this property is REQUIRED (See below, Grouping Route Segments).
schema:alternativeRouteSegmentGuide OPTIONAL Array of schema:URL An array of @id values pointing to Route Segment Guides describing alternative Route Segments that may be taken in preference to the declaring Segment.

The intention of the sequence attribute is to provide a guide regarding presentational order of the Route Segments to client applications, which will not necessarily correspond with the physical ordering of Segments along the Route. Ordering must thus be sequential even in cases where multiple alternative Segments exist.

Alternative Segments and Route Properties
Data publishers are cautioned to ensure that properties defined for the RouteGuide as a whole - in particular, routeDifficulty - remain applicable even once alternative segments are taken into account. If, for instance, one segment is quite difficult and another fairly easy, this SHOULD be indicated clearly at both the Route and Route Segment levels. Inheritance semantics between Route Guides and Route Segment Guides

Given that, for the most part, Route Guides and Route Segment Guides contain the same properties, how are they to be distributed between these two similar, but not identical, objects?

Modelling here is to be guided by the principle that some properties (e.g., publisher, author) are relatively generic, and hence heritable downwards from parent Route Guides to their Route Segment Guide children. Others, however, are specific to one level or another (for example, distance: the total length of a Route will necessarily be different from that of its individual Segments).

The table below indicates which Route Guide properties should be viewed as inherited, and which not. A 'Yes' value indicates that values for these properties defined on the parent Route Guide should be assumed to be shared by and relevant to children, unless values these properties are also declared on the children. Route Segment Guides. A 'No' indicates they should not: the values given at the Route Guide level can be assumed to be untrue or inaccurate in relation to individual Segments.

Property Inherited?
@type No
@id Yes
schema:name Yes
schema:url Yes
schema:author Yes
schema:datePublished Yes
schema:dateModified Yes
oa:verificationRecord Yes
schema:description Yes
schema:headline Yes
oa:activity Yes
oa:distance No
oa:indicativeDuration No
oa:startPoint No
oa:endPoint No
oa:pointOfInterest No
oa:accessibiltyDescription Yes
oa:gradient No
oa:surface Yes
oa:routeDifficulty Yes
oa:geoPath Yes
oa:mapImage Yes
oa:category Yes
oa:additionalInformation Yes
schema:amenityFeature No
oa:isLoop No
oa:riskInformation Yes
oa:legalAdvisory Yes
oa:routeAccessRestriction Yes
oa:suggestedEquipment Yes
schema:image Yes
schema:review Yes
schema:contactPoint Yes
oa:userContributedContent No
schema:isBasedOn Yes
oa:isJoinableThroughoutLength Yes
oa:segments N/A
oa:segmentGroups N/A
oa:alternativeSegmentTo N/A

When it comes to cases where a property may be declared either at the level of the Route or Route Segment Guide, modelling decisions must simply be made on the basis of scope: properties declared at the Route Guide level apply to the Route as a whole, and hence of each Segment within it; those declared on a Segment apply ONLY to that particular Segment.

4.7.14 Grouping Route Segments (oa:RouteSegmentGroup)

In the case of exceptionally lengthy routes (see e.g. ExploreKent's Elham Valley Way walk), individual Route Segment Guides may be grouped together into larger wholes to indicate, e.g., which Segments should ideally be covered in a single day, link together significant sites along the route, etc. In such cases, these larger groupings should be indicated using oa:RouteSegmentGroup objects.

Property Status Type Notes
@type REQUIRED String "RouteSegmentGroup"
@id RECOMMENDED URI A URI providing a unique, stable identifier for the resource. Note that an @id value is REQUIRED if alternativeGroupTo is supplied.
schema:name REQUIRED String The name of the grouping.
schema:description RECOMMENDED String A free text description of the grouping, and the rationale for seeing its member Route Segments as related in some way.
oa:includesSegments Array of URL REQUIRED The individual RouteSegmentGuide objects the RouteSegmentGroup comprises, as identified by the value of their @id.
alternativeGroupTo Array of URL REQUIRED Used to indicate that this RouteSegmentGroup's collection of RouteSegmentGuides serves as an alternative to the list of Route Segments given in this Array and expressed as a list of RouteSegmentGuide @ids. Where this value is provided, it is RECOMMENDED that the description supply reasons why one or another alternative (e.g. distance, accessibility) might be preferred.

4.7.15 Describing User Generated Content (oa:userGeneratedContent)

Users are often prolific in creating a wide range of supplemental material – e.g images, descriptions, GPX track recordings – for Routes, and such contributions can often considerably enrich RouteGuide data. The sheer – and open-ended – variety of possible contributions means that they are modelled using schema:CreativeWork.

The schema:CreativeWork model is extremely flexible, and implementers are encouraged to avail themselves of as much of this flexibility as desired; the properties and usage given below are provided simply as guidance and as potentially useful starting-points.

Property Status Type Notes
@type REQUIRED String "CreativeWork"
schema:creator RECOMMENDED Person The individual, howsoever identified (e.g. full name, user handle), responsible for creating the content.
schema:accountablePerson RECOMMENDED Person In the context of user-generated content, the accountablePerson is the editor, curator, or reviewer who approves and if necessary edits the user-contented submissions prior to publication.
schema:spatialCoverage REQUIRED String The spatialCoverage of a CreativeWork indicates the place(s) which are the focus of the content - typically, in this context, the location of the Route, or points along it.
schema:associatedMedia REQUIRED String The spatialCoverage of a CreativeWork indicates the place(s) which are the focus of the content - typically, in this context, the location of the Route, or points along it.

4.7.16 Describing RouteGuide Provenance (schema:isBasedOn)

As noted above, RouteGuides are often highly curated, with new information being added by Route maintainers, by users, or by other authors and editors. Because of this, there is a considerable chance of divergence in cases where a single RouteGuide has been republished by various organisations or on different websites.

To assist users and curators, it is therefore RECOMMENDED to provide links back to any earlier publications of the RouteGuide from which information has been harvested. Because each earlier publications is also a RouteGuide, and hence a [schema:CreativeWork], any of the properties characteristic of a schema:CreativeWork may be used here. The list below provides a recommended minimum.

Property Status Format Notes
@type REQUIRED String CreativeWork
schema:publisher REQUIRED schema:Organization of schema:Person The Organization or Person originally providing the information about the Route
schema:url RECOMMENDED schema:URL Link to original hosting site, which may contain additional or contextual information if available.
oa:version RECOMMENDED schema:Date or schema:DateTime The date upon which this RouteGuide information was harvested from the providing schema:publisher
schema:description OPTIONAL schema:Text Any further relevant information relevant to previous publications of the RouteGuide - e.g., any paper publications that might exist, etc.

4.8 Worked Example - The Wildlife Walk at Attingham Park

As the specification above is complex and somewhat abstract, a worked, real-life example illustrating one approach to Route Guide modelling is provided here. The data is drawn from The National Trust's Wildlife Walk at Attingham Park; to follow the example, it may be helpful to consult the originating website.

As will be evident from what follows, the intention of the example is not to demonstrate every aspect of the specification's use, nor to indicate how to resolve particularly problematic aspects of modelling e.g. complex paths. It is simply to illustrate a general approach to representation supporting a common use-case, and hence to provide concrete starting points for further work and consideration.

   "@context": ["", ""],
   "name":"Wildlife walk at Attingham Park",
      "name":"National Trust",
         "publisher":"Ordnance Survey",
      "landmark":"Attingham Park",
      "postalCode":"SY4 4TP",
      "description":"Visitor Reception",
         "publisher":"Ordnance Survey",
            "description":"0.5 miles (0.8km) along drive from main gates"
            "description":"Shrewsbury, 5 miles (8km)"
            "description":"Please check routes with Arriva bus services, then 0.5 miles (0.8km) walk along drive from main gates"
            "description":"The main entrance to Attingham Park is on the B43850 in the village of Atcham, 4 miles (6.4km) south of Shrewsbury"
         "value":"Toilets are in the Stables Courtyard, Bothy and Brewhouse."
         "value":"Carriage House café and Mansion tea-room serve a range of food and drink."
         "value":"Car parking is free (disabled bays available)."
         "value":"Mobility scooters are available to borrow (first come, first served)."
         "value":"Normal admission charges to the park apply."
      "telephone":"01743 708162",
      "email":"[email protected]",
   "description":"This circular walk starts in the Stables Courtyard at Attingham Park and follows the Deer Park walk in the beautiful parkland of this great estate.",
   "surface":"Walking on a mixture of grass, hoggin and woodland paths, this route is on a combination of level terrain and a few short inclines in the deer park. Paths may be uneven in places and may not be suitable for buggies or mobility scooters in muddy conditions. Please be careful on steps to the ice house.",
         "description":"From the car park make your way to Visitor Reception and through the Stables Courtyard bearing left towards the Walled Garden. As you walk towards the Walled Garden you are on part of the Mile Walk - a hoggin path designed by Thomas Leggett in 1770 for Noel Hill, the first Lord Berwick of Attingham Park. Hoggin is a mix of gravel, sand and clay ideal for building paths. In 2009, we restored the pond in the adjacent paddock and dugout hundreds of tonnes of hoggin to rebuild the Mile Walk."
         "description":"You will pass the Walled Garden on your left as you continue along this section of the Mile Walk. Stop in on your way past to see our historic bee house and new observation bee hive. The observation hive is made of clear acrylic and allows visitors to see the busy bees at work.",
            "landmark":"Walled Garden",
            "description":"Attingham's walled garden and orchard were probably built at the same time as the mansion in the 1780s for the first Lord Berwick. This productive area provided the Berwicks with a constant supply of fruit, flowers, vegetables and honey. It is still home to the Attingham bees who can safely be seen hard at work in the observation hive. Family activity: make your way through the orchard to the Shoulder of Mutton playfield to run off some steam or head to the frame yard to help our gardeners water the flowers, fruits and vegetables growing here.",
         "description":"At this point the path diverges - bear left following signs for the Deer Park Walk."
         "description":"Cross the cable stay bridge over the river Tern. With funding from Natural England this cable stay bridge was constructed in 2009. The new bridge provides improved access for buggies and mobility scooters. Attingham is host to around 5 miles of river, featuring beautiful stretches of the Severn and Tern. Our many ponds are a haven for wildlife of all sorts, from ducks, swans and otters to dragonflies.",
               "landmark":"River Tern",
               "description":"The River Tern is only 30 miles long flowing into the River Severn about a mile downstream. Its source is considered to be a lake in the grounds of Maer Hall in Staffordshire. Family activity: otters have been spotted from the bridge. Is there one in the river or on the river banks today?",
         "description":"At this fork in the path carry straight on up a gentle incline to continue with the walk. At further forks in the path follow signs for the 'Deer Park Walk'. For buggies (in muddy conditions) and mobility scooters follow the right fork labelled 'Shortcut' through the gate which takes you along the bank of the Tern to rejoin the walk at point 8.",
            "description":"At this point, just through the gate to the deer park you will see an area where families have been building dens. Why not have a go as part of our '50 Things to do before you're 11¾'? Please stay in front of the signs that ask you to not go any further into the area due to the deer sanctuary.",
         "description":"After walking through the woodland the path opens out along the top of the Deer Park, with the woodland on your left and the deer park to your right. Look closely in the bracken and ferns and you might be lucky to spot some of our deer herd! Please note: during parts of the year sections of the Deer Park may be closed, please follow any signed diversions on your route.",
            "landmark":"Attingham Deer",
            "description":"Attingham is home to approximately 250 semi-wild fallow deer, all direct descendents of the fallow deer here at the creation of the Deer Park in 1797. Attingham's last lord Thomas was particularly fond of the deer and fed them daily, with special favourites eating from his hand. Family activity: during the winter you can watch the deer being fed at 2pm on Saturdays, Sundays and every day in the Christmas and half term school holidays (except 25 December).",
         "description":"Keep walking along the grass path with the woodland on your left, until you get to the Repton Oak. Lots of different animals live in the deer park and woodland areas at Attingham, especially in old trees which are havens for wildlife, bats, birds, insects, mosses and lichens. There are five species of bats at Attingham including over 1,000 pipistrelle bats. Family activity: the barn owl, raven and buzzard are the top predators here - can you spot any flying over the deer park?",
               "landmark":"The Repton Oak",
               "description":"This venerable oak may have started life in the reign of King Edward III (1327-1377), our best guess is that it is about 650 years old. Originally marking the boundary between the parishes of Wroxeter and Atcham this old oak is now one of the wonders of Attingham park.",
         "description":"A short while after passing the Repton Oak the path will begin to lead you down the hill towards the mansion. Go through the gate, across the bridge and turn right to take a look at the Ice House. Please note: There is no light in the ice house and is lit by natural light from its entrance. Be careful walking down the narrow uneven steps into the ice house. After you've visited the ice house follow the path passing the mansion on your right hand side and continue to bear right, past the tea-room and toilets before turning left to return to the Stables Courtyard.",
            "landmark":"The ice house",
            "description":"This mound was an ice house probably built for Noel Hill, the first Lord Berwick in the late 18th century; it was converted in 1850 when a wheel pump was installed to provide the mansion with water from the River Tern. Before that, there was a corn mill on this site from the 13th century. Family activity: the ice house is dark and damp and the perfect home for lots of insects - can you find any?",
               "name":"Stables Courtyard",

All example data provided by kind permission of the National Trust

4.8.1 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. Versioning Policy

The broad goal is to ensure that future versions of this specification remain backwards compatible. This will ensure that published data remains valid.

The question of how versioning of this specification will relate to other OpenActive standards is currently an open question, and one to be debated in the W3C OpenActive Group. Relationship with and SKOS

This specification draws heavily on [SCHEMA-ORG] and [SKOS] to define its core data model. This is supplemented with additional custom types and properties that capture additional requirements for the physical activity sector.

The [SCHEMA-ORG] and [SKOS] specifications define additional properties that are not directly referenced in this document.

Rather than reflect the whole of these specifications in this document, we have chosen to include those types and properties that:

  • are necessary to document a basic framework for publishing opportunity data
  • are useful to highlight to encourage consistent usage across the community
  • have stricter conformance rules that used by [SCHEMA-ORG]. For example where we have agreed to specific uses of properties to increase quality and consistency in how data is being published

However data publishers are free to use any additional types and properties where useful. [SCHEMA-ORG] in particular provides a source of a wide range of additional properties for describing Events, Places, Organisations, etc.

For example an application may wish to share reviews of events, places or clubs. The schema:review property and its related data model can be used for this purpose, without requiring revisions to this specification. Defining Custom Vocabularies

Individual publishers, or members of the community may identify new requirements for publishing opportunity data that are not covered by this specification or [SCHEMA-ORG].

These new requirements might result in:

  • submission of proposals to the OpenActive Community Group for revisions to this specification
  • creation of new specifications that support the needs fo specific types of publisher. For example a group of publishers might wish to define a detailed specification for describing the characteristics of cycle tracks
  • creation of bespoke properties that support the needs of a specific publisher and their data users

In all of these cases we encourage discussion of requirements and extensions via the OpenActive Community Group, as the primary forum for standarding the publication of opportunity data. Defining and Using Custom Namespaces

The data model described in this specification is defined in the OpenActive JSON-LD context defined by [OpenActive-Vocabulary].

They SHOULD also:

  • publish public, human-readable documentation that describes their extension, including any custom properties, types and controlled vocabularies that are being used
  • share the documentation with the OpenActive community group
  • look for opportunities to align their data model with revisions to the standard and other extensions defined in the community

Publish MUST also

  • avoid using names for custom types or properties that clash with the core data model
  • publish a custom JSON-LD context to provide a machine-readable version of their extension
  • include a reference to their context in their published data

A full tutorial on creating JSON-LD contexts is outside the scope of this specification.

[JSON-LD] allows data to be published with reference to multiple contexts.

Assuming that a JSON-LD context using the prefix ext: was published to, then the following example shows how to use this extension:

Example 6: Example of a custom context

    "@context": [
    "type": "Event",
    "ext:myCustomProperty": "foo"

Publishers MUST NOT use unprefixed property and type names.

Using a separate context and prefixed names will help to clarify for users when a dataset is referencing one or more extensions. Beta Namespace

The [OpenActive-Beta-Namespace] provides a custom namespace that can be used by publishers experimenting with new properties that are likely to be added to the core specification.

It is defined as a convenience to help document properties that are in active testing and review by the community. Publishers SHOULD NOT assume that properties in the beta namespace will either be added to the core specification or be included in the namespace over the long term.

Publishers needing additional custom properties SHOULD define their own namespace.

A. Acknowledgements

This section is non-normative.

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

B. References

B.1 Normative references

Representation of dates and times. ISO 8601:2004.. International Organization for Standardization (ISO). 2004. ISO 8601:2004. URL:
JSON-LD 1.0. W3C. W3C Recommendation. URL:
OpenActive Beta Namespace. OpenActive Community Group. URL:
OpenActive Vocabulary. OpenActive Community Group. URL:
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL:
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL:
SKOS Simple Knowledge Organization System Primer. W3C. W3C Note. URL: