Copyright © 2019 the Contributors to the Dataset API Discovery 0.1 Specification, published by the OpenActive Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.
This document specifies a dataset site and embedded JSON-LD document that together describe an open data dataset and define related APIs that are available to manipulate it.
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.
This document represents an early Editors Draft of the planned API design. It is likely to change between now and its final version. These early drafts are intended to help developers provide that feedback by developing proof-of-concept implementations. We encourage developers to explore this API and contribute to the development of the specification.
If you wish to make comments regarding this document, please send them to [email protected] (subscribe, archives).
This section is non-normative.
The document is an output of the OpenActive Community Group. As part of the OpenActive initiative, the community group is developing standards that will promote the publication and use of open opportunity data in helping people to become more physically active.
This specification aims to build on existing work by the WebAPI Discovery Community Group and the Schema.org discussion, providing a profile and guidance specifically both for open data publishers and implementers of Web APIs that manipulate openly available datasets. It also aims to provide conformance rules to ensure that implementers include the details necessary to allow Data Consumer to reliably integrate with standards-compliant services without human intervention.
The specification defines the requirements of a Dataset Site provided by a Data Publisher (server) for use by a Data Consumer (client). It includes high level requirements for human-readable content, and detailed requirements and conformance rules for machine-readable content.
Dataset Sites that conform to this specification will be:
WebAPI Search.Dataset Sites will also provide the following information about the implementation of APIs it describes:
Note that although this specification of the OpenActive Community Group, it is designed to apply to any open dataset where an API is available to manipulate it.
By design this specification will not define some types of functionality.
These have been declared as permanently out of scope because they are adequately covered by existing specifications:
The document is primarily intended for the following audiences:
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.
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.A Dataset Site is a human and machine readable web page ("Dataset Page") that describes a dataset and the APIs available to interact with it, with associated functionality that allows for feedback to be provided about the dataset.
The purpose of a Dataset Site is to provide:
<script type="application/ld+json">
{
"@context": [
"https://schema.org",
"https://openactive.io/"
],
"@type": "Dataset",
"id": "https://data.example.com/",
"url": "https://data.example.com/",
"name": "Acme Leisure Sessions and Facilities",
"description": "Near real-time availability and rich descriptions relating to the sessions and facilities available from Acme Leisure, published using the OpenActive Modelling Specification 2.0.",
"keywords": [
"Sessions",
"Facilities",
"Activities",
"Sports",
"Physical Activity",
"OpenActive"
],
"license": "https://creativecommons.org/licenses/by/4.0/",
"distribution": [
{
"additionalType": "https://openactive.io/SessionSeries",
"encodingFormat": "application/vnd.openactive+json; rpde=1.0, model=2.0",
"contentUrl": "https://example.com/open-api/feeds/session-series",
"@type": "DataDownload",
"name": "SessionSeries"
},
{
"additionalType": "https://openactive.io/ScheduledSession",
"encodingFormat": "application/vnd.openactive+json; rpde=1.0, model=2.0",
"contentUrl": "https://example.com/open-api/feeds/sessions",
"@type": "DataDownload",
"name": "ScheduledSession"
},
{
"additionalType": "https://openactive.io/FacilityUse",
"encodingFormat": "application/vnd.openactive+json; rpde=1.0, model=2.0",
"contentUrl": "https://example.com/open-api/feeds/facility-uses",
"@type": "DataDownload",
"name": "FacilityUse"
},
{
"additionalType": "https://openactive.io/Slot",
"encodingFormat": "application/vnd.openactive+json; rpde=1.0, model=2.0",
"contentUrl": "https://example.com/open-api/feeds/slots",
"@type": "DataDownload",
"name": "Slot"
}
],
"potentialAction": [
{
"@type": "OpenBookingAction",
"target": {
"@type": "EntryPoint",
"urlTemplate": "https://example.com/api/orders/{uuid}",
"encodingType": [
"application/vnd.openactive+jsonld; model=2.0, booking=1.0"
],
"httpMethod": "PUT"
},
"supportingData": {
"@type": "DataFeed",
"distribution": [
{
"@type": "DataDownload",
"name": "Order",
"additionalType": "https://schema.org/Order",
"encodingFormat": [
"application/vnd.openactive+json; model=2.0, booking=1.0, rpde=1.0"
],
"contentUrl": "https://example.com/api/feeds/offers"
}
]
}
}
],
"discussionUrl": "https://github.com/example/opendata/issues",
"documentation": "https://docs.example.com/",
"inLanguage": "en-GB",
"publisher": {
"legalName": "Acme Leisure Ltd",
"logo": {
"@type": "ImageObject",
"url": "https://example.com/logo.png"
},
"email": "[email protected]",
"@type": "Organization",
"name": "Acme Leisure",
"description": "We are able to continually reinvest in facilities, products and importantly people.",
"url": "https://example.com/"
},
"datePublished": "2019-02-20T13:22:28.7743707Z",
"schemaVersion": "https://www.openactive.io/modelling-opportunity-data/2.0/"
}
</script>Future iterations of the specification be shaped by the OpenActive community, and we encourage you to get involved.
This section is non-normative.
The editors thank all members of the OpenActive Community Group for their contributions.