Copyright © 2018-2020 the Contributors to the Route Guide Specification - Editor's Draft Specification, published by the OpenActive Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.
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 ([SCHEMA-ORG]) types and properties. This existing work provides a useful existing framework around which the OpenActive Community Group can build additional data standards.
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).
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.
This specification has been developed to meet a broad set of requirements.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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
This specification is divided into three main sections:
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].
The following typographic conventions are used in this specification:
markupNotes 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.The data model described in the following sections reuses existing standards and vocabularies which have then been extended to cover the additional requirements needs to support the publication of opportunity data.
The Simple Knowledge Organisation System ([SKOS]) is a W3C standard for publishing taxonomies and category schemes. It can be used to help publish and organise Activity Lists and to describe Physical Activities.
Schema.org [SCHEMA-ORG] provides an existing well-used and documented data model for publishing data to the web. It provides an existing model for describing Events, Organisations, People, and Places.
Both standards are widely used, and can be used to publish data in a variety of structured formats, including [JSON-LD].
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 Schema.org 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 schema.org's CreativeWork type.
The rest of this specification makes use of the following namespaces:
dc:http://purl.org/dc/terms/schema:https://schema.org/skos:http://www.w3.org/2004/02/skos/core#geo:http://www.w3.org/2003/01/geo/wgs84_pos#oa:https://openactive.io/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](https://openactive.io/ns/oa.jsonld) defined by [OpenActive-Vocabulary], which is accessible at https://openactive.io/ 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](https://www.w3.org/TR/json-ld/#specifying-the-type) and [@id](https://www.w3.org/TR/json-ld/#node-identifiers) properties to simple keys (type and id). This further limits the amount of JSON-LD syntax exposed to developers.
The following table provides a high-level summary of how the concepts introduced in the previous sections map to definitions in SKOS, Schema.org and the OpenActive Vocabulary ([OpenActive-Vocabulary]).
| Concept | Mapping | Notes |
|---|---|---|
| Activity List | skos:ConceptScheme | Activity lists are controlled vocabularies and map well to the definition of a SKOS Concept Scheme. |
| Physical Activity | skos:Concept | Individual Physical Activities can be represented as individual SKOS concepts |
| Place | schema:Place | As well as the general definition of a Place, Schema.org defines sub-types including |
| Organization | schema:Organization | Covers all types of organisations, including companies, clubs, etc |
| Person | schema:Person | An individual person |
This specification adopts the same approach as Schema.org 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:
This specification provides three properties for identifying resources:
@id - is used to assign a globally unique URI to a resource. This may resolve to further machine-readable
information about the resource, e.g. as a reference to an API endpoint. When supplied, this URI MUST be stable and unchanging over time. Applications harvesting and
indexing opportunity data SHOULD use this as the unique identifier for the resource@id available.In short, the @id property provides a unique global identifier, while the schema:url provides a means to provide a link to
a public web page about a resource.
If applicable then publishers may choose to use the same URI for these two properties. If an @id property is not provided then
applications MAY choose to rely on the value of the schema:url property as a unique identifier.
The option to use two different URLs is useful when there is a need to distinguish between a unique identifier and a public resource. For example a platform hosting opportunity data may need to assign a unique identifier to a resource that is separate to its public web page.
{
"@context": "https://openactive.io/",
"type": "RouteGuide",
"id": "http://routes.openactive.io/id/12345",
"url": "https://www.nationaltrust.org.uk/avebury/trails/avebury-archaeology-walk",
"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.
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:
{
"@context": "https://openactive.io/",
"@type": "RouteGuide",
"@id": "https://routes.openactive.io/id/12345",
"url": "https://www.nationaltrust.org.uk/avebury/trails/avebury-archaeology-walk",
"name": "Avebury Archaeology Walk"
}
<oa:RouteGuide xmlns:oa="https://openactive.io/" xmlns:schema="https://schema.org">
<oa:id>https://routes.openactive.io/id/12345</oa:id>
<schema:name>Avebury Archaeology Walk</schema:name>
<schema:url>https://www.nationaltrust.org.uk/avebury/trails/avebury-archaeology-walk</schema:url>
</oa:RouteGuide>It is expected that data publishers will adopt whatever format best suits their use-case and supports their frequency of updating.
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.
E.g.:
<script type="application/json" id="example">
{
"@context": "https://openactive.io/",
"@type": "RouteGuide",
"@id": "https://routes.openactive.io/id/12345",
"url": "https://www.nationaltrust.org.uk/avebury/trails/avebury-archaeology-walk",
"name": "Avebury Archaeology Walk"
}
</script>
The following sections include more detail about the properties available to describe each type of resource. Some properties are considered to be essential to ensure the provision of a minimally useful set of information about each resource. These REQUIRED properties MUST be provided.
All other properties are considered to be OPTIONAL. Some properties have been marked as RECOMMENDED. Publishers SHOULD provide these properties if it is feasible to do so, as they will improve the quality and usability of their data.
Where data is not available to populate RECOMMENDED and OPTIONAL properties, publishers MUST exclude these from their data. Published data MUST not include properties with null values, empty strings or empty arrays.
Data publishers MAY include additional properties, e.g. from Schema.org or other vocabularies when helpful to describe their data. See the section on Extending the Model for more information.
Applications that consume opportunity data MUST ignore any properties that they don't understand. This allows data publishing practices within the sector to evolve as required.
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.
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 https://openactive.io/activity-list#_4a19873e-118e-43f4-b86e-05acba8fb1de ("cycling"), https://openactive.io/activity-list#_95092977-5a20-4d6e-b312-8fddabe71544 ("walking") https://openactive.io/activity-list#_72ddb2dc-7d75-424e-880a-d90eabe91381 ("running"), https://openactive.io/activity-list#_45a372d9-baca-4f6c-859f-04de3efae742 ("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 https://openactive.io/Gravel, https://openactive.io/Paved, https://openactive.io/BareEarthOrBedrock, https://openactive.io/ShortVegetation, https://openactive.io/RoughVegetationOrCrop, https://openactive.io/HardSurface(Stoney), https://openactive.io/HardSurface(Sealed), and https://openactive.io/BoardwalkOrTimber |
| 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 |
oa:geoPath and oa:mapImageCartographic 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 schema.org 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 schema.org MapCategoryType or OpenActive enumeration value (see 'Notes') |
May be taken from the MapCategoryType values defined by schema.org; alternatively, https://openactive.io/RouteMap, https://openactive.io/ElevationMap, or https://openactive.io/CustomMap 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 schema.org mapCategoryType enumeration (though see 'Notes') |
May be taken from the MapCategoryType values defined by schema.org; alternatively, https://openactive.io/RouteMap, https://openactive.io/ElevationMap, and https://openactive.io/CustomMap 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. |
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 Schema.org'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. |
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 |
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 |
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: https://openactive.io/Bus, https://openactive.io/Rail, https://openactive.io/Bicycle, https://openactive.io/Road, or https://openactive.io/Foot. |
| schema:description | REQUIRED | schema:Text | Instructions for navigation to the destination by means of the oa:transportMode |
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.
| 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](https://www.w3.org/2009/08/skos-reference/skos.html#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. https://www.ramblers.org.uk/go-walking/about-group-walks/walks-difficulty.aspx |
oa:RouteLegalAdvisory)Users of Routes, particularly in rural areas, need to be apprised of their legal status - that is to say, whether and under what conditions they are legally allowed to avail themselves of all sections of the Route. In most cases this can be done concisely by indicating the oa:routeDesignation. Further nuances or exceptional cases should be dealt with in more detail using the description and legalInformationURL fields.
| Property | Status | Type |
|---|---|---|
| @type | REQUIRED | String |
| oa:routeDesignation | RECOMMENDED | oa:RouteDesignation |
| schema:description | OPTIONAL | schema:Text |
| oa:legalInformationURL | OPTIONAL | schema:URL |
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. |
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 |
In the UK, the number of legal statuses a Route might have is quite small, and all Routes will therefore be some assortment of:
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 https://www.ordnancesurvey.co.uk/blog/2011/08/rights-of-way/.
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. https://vscg.org/guiding-principles/risk-control |
| oa:trafficDescription | OPTIONAL | schema:Text |
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. https://canalrivertrust.org.uk/notices/winter |
| oa:routeAccessRestrictionTimeSpan | OPTIONAL | schema:Text | Brief text indicating when the pragmaticRestriction applies, e.g, "Winter", "2020-01-01 to 2020-03-31" |
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. |
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:
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.
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.
Segments MUST NOT themselves contains Segments. That is to say, the segments attribute is FORBIDDEN for Route Segment Guides.
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:
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.
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.
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.
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.
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. |
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. |
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. |
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": ["https://openactive.io", "https://schema.org"],
"@id":"https://routes.openactive.io/nt/12345",
"@type":"RouteGuide",
"name":"Wildlife walk at Attingham Park",
"publisher":{
"@type":"Organization",
"name":"National Trust",
"url":"https://www.nationaltrust.org.uk/"
},
"url":"https://www.nationaltrust.org.uk/attingham-park/trails/wildlife-walk-at-attingham-park",
"distance":{
"@type":"QuantitativeValue",
"value":4,
"unitCode":"KTM"
},
"activity":"https://activity-list-editor.openactive.io/_95092977-5a20-4d6e-b312-8fddabe71544",
"mapReference":[
{
"@type":"MapReference",
"publisher":"Ordnance Survey",
"mapSeries":"Landranger",
"mapNumber":"126"
}
],
"gradient":{
"@type":"RouteGradient",
"gradientTerm":"Moderate"
},
"category":[
"Dog-friendly"
],
"indicativeDuration":[
{
"@type":"IndicativeDuration",
"activity":"https://activity-list-editor.openactive.io/_95092977-5a20-4d6e-b312-8fddabe71544",
"duration":"P45M"
},
{
"@type":"IndicativeDuration",
"activity":"https://activity-list-editor.openactive.io/_95092977-5a20-4d6e-b312-8fddabe71544",
"duration":"P1H"
}
],
"image":"https://nt.global.ssl.fastly.net/images/1431730349476-attinghamparkwildlifewalk.jpg?width=1920&auto=webp&crop=16:7",
"startPoint":{
"@type":"RoutePoint",
"landmark":"Attingham Park",
"village":"Atcham",
"town":"Shrewsbury",
"region":"Shropshire",
"postalCode":"SY4 4TP",
"description":"Visitor Reception",
"mapReference":{
"@type":"MapReference",
"publisher":"Ordnance Survey",
"gridReference":"SJ5501109896"
},
"transportNote":[
{
"@type":"TransportNote",
"transportMode":"https://openactive.io/Foot",
"description":"0.5 miles (0.8km) along drive from main gates"
},
{
"@type":"TransportNote",
"transportMode":"https://openactive.io/Train",
"description":"Shrewsbury, 5 miles (8km)"
},
{
"@type":"TransportNote",
"transportMode":"https://openactive.io/Bus",
"description":"Please check routes with Arriva bus services, then 0.5 miles (0.8km) walk along drive from main gates"
},
{
"@type":"TransportNote",
"transportMode":"https://openactive.io/Road",
"description":"The main entrance to Attingham Park is on the B43850 in the village of Atcham, 4 miles (6.4km) south of Shrewsbury"
}
]
},
"isLoop":true,
"mapImage":{
"@type":"Map",
"mapType":"https://openactive.io/RouteMap",
"encodingFormat":"image/jpeg",
"url":"https://nt.global.ssl.fastly.net/images/mapattinghamwildlifewalkmap.jpg?width=1170&auto=webp&crop=16:9"
},
"amenityFeature":[
{
"@type":"LocationFeatureSpecification",
"value":"Toilets are in the Stables Courtyard, Bothy and Brewhouse."
},
{
"@type":"LocationFeatureSpecification",
"value":"Carriage House café and Mansion tea-room serve a range of food and drink."
},
{
"@type":"LocationFeatureSpecification",
"value":"Car parking is free (disabled bays available)."
},
{
"@type":"LocationFeatureSpecification",
"value":"Mobility scooters are available to borrow (first come, first served)."
},
{
"@type":"LocationFeatureSpecification",
"value":"Normal admission charges to the park apply."
}
],
"contactPoint":{
"telephone":"01743 708162",
"email":"[email protected]",
"url":"http://www.nationaltrust.org.uk/attingham-park/"
},
"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.",
"segments":[
{
"@type":"RouteSegmentGuide",
"sequence":1,
"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."
},
{
"@type":"RouteSegmentGuide",
"sequence":2,
"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.",
"pointofInterest":{
"@type":"RoutePoint",
"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.",
"category":[
"Garden"
]
}
},
{
"@type":"RouteSegmentGuide",
"sequence":3,
"description":"At this point the path diverges - bear left following signs for the Deer Park Walk."
},
{
"@type":"RouteSegmentGuide",
"sequence":4,
"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.",
"pointofInterest":[
{
"@type":"RoutePoint",
"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?",
"category":[
"Natural"
]
}
]
},
{
"@type":"RouteSegmentGuide",
"sequence":5,
"alternativeRouteSegment":{
"@type":"alternativeRouteSegment",
"alternativeSegmentTo":8
},
"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.",
"pointofInterest":{
"@type":"RoutePoint",
"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.",
"category":[
"Activity"
]
}
},
{
"@type":"RouteSegmentGuide",
"sequence":6,
"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.",
"pointofInterest":{
"@type":"RoutePoint",
"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).",
"category":[
"Wildlife"
]
}
},
{
"@type":"RouteSegmentGuide",
"sequence":7,
"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?",
"pointofInterest":[
{
"@type":"RoutePoint",
"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.",
"category":[
"Historic"
]
}
]
},
{
"@type":"RouteSegmentGuide",
"sequence":8,
"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.",
"pointofInterest":{
"@type":"RoutePoint",
"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?",
"category":[
"Historic"
]
},
"amenityFeature":[
{
"@type":"Toilets",
"name":"Toilets",
"value":true
},
{
"@type":"LocationFeatureSpecification",
"name":"Stables Courtyard",
"value":true
},
{
"@type":"LocationFeatureSpecification",
"name":"Tea-room",
"value":true
}
]
}
]
}All example data provided by kind permission of the National Trust
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.
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.
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:
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.
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:
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.
The data model described in this specification is defined in the OpenActive JSON-LD context defined by [OpenActive-Vocabulary].
They SHOULD also:
Publish MUST also
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 https://example.org/custom.jsonld, then
the following example shows how to use this extension:
{
"@context": [
"https://openactive.io/",
"https://example.org/custom.jsonld"
],
"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.
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.
This section is non-normative.
The editors thank all members of the OpenActive CG for contributions of various kinds.