"@context" and field names; Namespaces and Deprecation

Last updated 2 months ago

Properties and Namespaces

In the world of linked data on the web, "namespaces" ("@context") are a collection of "properties" **(fields) which have a well defined meaning.

There are five primary namespaces which are used within imin data, and which are covered by our deprecation policy. These are listed below. Clicking on the name of each namespace will take you to a list of properties within it.

imin data is valid JSON-LD, which means that properties will always exist in one of the specified namespaces ("@context").

Namespace

Prefix

URL

Bundles

Prefix Required

Status

Deprecation Policy

schema.org

schema

https://schema.org/

No

Living Standard

SKOS

skos

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

No

Stable

OpenActive

oa

https://openactive.io/

schema.org, SKOS

No

Stable

Yes

imin

imin

https://imin.co/

Yes

Stable

Yes

OpenActive Beta

beta

https://openactive.io/ns-beta

Yes

Experimental

[Extensions]

*

*

Yes

Experimental

The OpenActive modelling specification includes a "profile" (subset) of schema.org and SKOS which has been defined for OpenActive use, along with the specification for OpenActive namespace.

Descriptions and examples of the most commonly used properties from schema.org and SKOS, together with all properties from OpenActive, are included in the OpenActive developer documentation. imin and OpenActive Beta namespaces are documented separately at the links above.

Please note that properties defined outside of the OpenActive modelling specification and imin namespace are not subject to the imin deprecation policy, and are subject to change at any time. We strongly encourage a defensive data consumption approach, however if you are considering one of these fields to drive critical production functionality, please get in touch with us at hello@imin.co and we will work with you to propose your use case to the OpenActive W3C Community Group, and move the field into either the OpenActive or imin namespace.

Understanding which namespaces are in use

When reading a response which contains JSON-LD, you'll see an "@context" property to let you know which namespaces are in use.

Three key things to remember:

  • The OpenActive namespace bundles SKOS and schema.org namespaces inside it too.

    • So writing

      "@context": [ "https://openactive.io/" ]

      is the same as writing

      "@context": [ "https://openactive.io/", "https://schema.org", "http://www.w3.org/2004/02/skos/core#" ]

  • OpenActive, SKOS and schema.org namespaces do not require a prefix when using them.

    • So you must write "name": "Tai chi Class" instead of "schema:name": "Tai chi Class"

  • All other properties always require a prefix.

    • You must write "imin:fullAddress" and never "fullAddress"

Example

The following example references the namespaces of OpenActive (which automatically includes schema.org and SKOS) and imin.

{
"@context": [
"https://openactive.io/",
"https://imin.co/"
],
"type": "SessionSeries",
"name": "Tai chi Class",
"url": "http://www.example.org/events/1",
"location": {
"type": "Place",
"imin:fullAddress": "ExampleCo Gym Kingswood, 1 High Street, Kingswood, South Gloucestershire, BS1 4SD"
}
}

Namespace Evolution and Deprecation

schema.org

Schema.org is a collaborative, community activity with a mission to create, maintain, and promote schemas for structured data on the Internet, on web pages, in email messages, and beyond. It was founded by Google, Microsoft, Yahoo and Yandex.

The terms of schema.org continue to evolve through lively discussions on their mailing list and GitHub issues. Often properties are added for some specific use case, and their potential relationship to other areas of schema.org only becomes clear later. This gives rise to changes in textual definition and property-to-type associations that gradually make schema.org more coherent, without introducing radical changes in meaning. Consumers of schema.org data can generally rely on schema.org term meanings not changing dramatically; however term definitions often evolve gradually over time, to accommodate new usage scenarios or to improve usability. When schema.org properties are occasionally deprecated, they stay in the namespace so that they can still be used and are simply referenced to their replacement property.

The OpenActive W3C Community Group and imin both contribute to discussions within schema.org, however consensus involves a number of stakeholders and can be time consuming to reach.

Where a schema.org property is explicitly included in the OpenActive modelling specification, it follows the OpenActive versioning policy. Where a schema.org property is not included in the OpenActive modelling specification, its usage may be subject to change, however due to schema.org's internal processes and policies it is highly unlikely to change in name, and more likely to subtly change in definition.

SKOS: Simple Knowledge Organization System

The SKOS specification, published in 2009, is centred around the Concept type, and provides a mechanism for organising these concepts into a hierarchy. It is used for the OpenActive activity list and other controlled vocabularies where an enumeration of specific terms are defined.

This specification is not expected to be updated, however the use of the specification within OpenActive is subject to change in line with the OpenActive versioning policy.

OpenActive

The OpenActive W3C Community Group was established with the objective of facilitating the sharing and use of physical activity data. We very much encourage you to join the conversation and help shape the standards and our future API iterations through this process.

The OpenActive modelling specification defines a subset ("profile") of schema.org and SKOS which has been defined for OpenActive use, along with additional properties that feature in the OpenActive namespace.

Descriptions and examples of the OpenActive modelling specification , including the defined subset ("profile") of schema.org and SKOS, together with all properties from the OpenActive namespace, are included in the OpenActive developer documentation.

The OpenActive versioning policy within that specification specifies the use of version numbering to indicate potential for breaking changes. Minor versions, e.g. 1.1, 1.2, etc should be backwards compatible. Major versions, e.g. 2.0, 3.0 are likely to include breaking changes. It is estimated that such breaking major version releases will only occur at most annually. imin will strive to align major version releases with OpenActive major version releases, with any deprecated imin API major version maintained for a period in accordance with the imin deprecation policy.

The properties defined in the OpenActive modelling specification are subject to the imin deprecation policy.

imin namespace

The imin namespace is maintained to facilitate the early stabilisation of properties ahead of their broader adoption and standardisation. imin works as part of the OpenActive W3C Community Group to promote the use cases represented by the properties within this namespace, with the intention of standardising them into the OpenActive modelling specification over time, where applicable.

When a property "graduates" from the imin namespace into the OpenActive modelling specification, it will be maintained as a duplicate property for 12 months, and deprecated in accordance with the imin deprecation policy.

OpenActive Beta

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. Data consumers should not assume that properties in the beta namespace will either be added to the core specification or be included in the OpenActive namespace over the long term.

Please note that OpenActive Beta namespace properties are not subject to the imin deprecation policy, and are subject to change at any time. We strongly encourage a defensive data consumption approach, however if you are considering one of these fields to drive critical production functionality, please get in touch with us at hello@imin.co and we will work with you to propose your use case to the OpenActive W3C Community Group, and move the field into either the OpenActive or imin namespace.

Extensions

imin data sometimes contains additional namespaces, known as extensions. Data publishers may use these extensions to include additional fields which are not currently being considered as part of the evolving OpenActive standards.

Please note that extension properties are not subject to the imin deprecation policy, and are subject to change at any time. We strongly encourage a defensive data consumption approach, however if you are considering one of these fields to drive critical production functionality, please get in touch with us at hello@imin.co and we will work with you to propose your use case to the OpenActive W3C Community Group, and move the field into either the OpenActive or imin namespace.

Example

In the example below the "britishcycling:gpxFile" field is defined by an extension provided by British Cycling, using their custom namespace "http://data.goskyride.com/opendata/britishcycling.jsonld".

{
"@context": [
"https://openactive.io/",
"http://data.goskyride.com/opendata/britishcycling.jsonld"
],
"type": "Event",
"name": "Wheel Do It! - Blindside loop (with Betty-Ann)",
...
"britishcycling:gpxFile": "https://lr-media.staging.phoenixdigital.agency/download/2c89c364a0738a26fde9b68eb35bfeb0",
"meetingPoint": "Start of Loxley Road just past the bus stop, which is immediately after the pedestrian crossing/traffic lights."
}