Dataset API Discovery 0.1

Abstract

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.

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.

Note

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

1. Introduction

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 for Web APIs that manipulate openly available datasets, and 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.

1.1 Scope and requirements

Dataset Sites that conform to this specification will be:

Schema.org compatible - Remain fully compatible with schema.org, and machine-readable by Data Consumers that can read Schema.org Dataset and future Schema.org WebAPI embedded JSON-LD.
Google compatible - Use embedded JSON-LD to enable indexing by Google Dataset Search, and any future Google WebAPI Search.
DCAT compatible - Include DCAT markup to ensure compatibility with the widest range of open data catalogues.
Sufficient for automated integration - Allow Data Consumers to reliably integrate with services that are compliant with a standardised API specification (e.g. a Swagger specification) without requiring additional configuration or human intervention.
Human readable - Include human-readable content to allow developers to successfully integrate discover, consume and integrate with the Data Publisher's dataset and API.
Interactive - Include a mechanism for Data Consumers to provide feedback to Data Publishers in the open, and subscribe to updates from Data Publishers.

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.

1.1.1 Functionality that is out of scope

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:

API documentation - each system should provide its own documentation, the specification only requires that such documentation exists.
API specification and API definition - many existing formats are available for API specification (e.g. Swagger, RAML, etc.).

1.2 Audience

The document is primarily intended for the following audiences:

Software developers who want to publish a Dataset Site ("Data Publishers").
Software developers building client libraries or tools.
Software developers writing applications that will use Dataset Sites ("Data Consumers").

3. Typographical Conventions

The following typographic conventions are used in this specification:

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

Note

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

Example 1

Examples are in light khaki boxes, with khaki left border, and with a
numbered "Example" header in khaki. Examples are always informative.
The content of the example is in monospace font and may be syntax colored.

5. Dataset Site

5.1 Definition

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.

5.2 Purpose

The purpose of a Dataset Site is to provide:

A web page that can be referenced when discussing the dataset.
A human and machine readable licence associated with the data (the Dataset Page contains invisible metadata which allows its details to be read automatically).
A human and machine readable rights statement to specify how dataset users (innovators who want to build on top of/use data) should attribute your data.
An accessible "single point of truth" that explains where the data can be found.
Details ("documentation") and historical record ("changelog") relating to the format of the data, including the specifications it follows, and the data fields it contains.
A place where the community can contribute with comments, and raise issues.
A mechanism by which Data Consumers can subscribe to get updates about changes to the data format, specifications and fields.
A human and machine readable description of any APIs that can be used to manipulate the data, and the process to gain access to such APIs.

Dataset API Discovery 0.1

Draft Community Group Report 13 March 2019

Abstract

Status of This Document

1. Introduction

1.1 Scope and requirements

1.1.1 Functionality that is out of scope

1.2 Audience

2. Conformance

3. Typographical Conventions

4. Key Actors

5. Dataset Site

5.1 Definition

5.2 Purpose

5.3 Human-readable Dataset Page

5.4 Dataset Markup

5.4.1 JSON-LD

5.4.2 DCAT

5.5 API Markup

5.6 JSON-LD

5.7 Documentation

6. Future versions of this API

A. Acknowledgements

B. References

B.1 Normative references