Dataset API Discovery 0.1

Draft Community Group Report

Latest editor's draft:
https://openactive.io/dataset-api-discovery/EditorsDraft/
Editors:
Leigh Dodds (Open Data Institute)
Nick Evans (Open Data Institute)
Participate:
GitHub openactive/dataset-api-discovery
File a bug
Commit history
Pull requests
Version:
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:

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:

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.

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

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.

4. Key Actors

Data Publisher
The application that is publishing the Dataset Site, that will also be making available open data endpoints and API endpoints for use by the Data Consumer.
Data Consumer
The application or human that is reading the Dataset Site in order to make use of the available open data endpoints and API endpoints.

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:

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

Future iterations of the specification be shaped by the OpenActive community, and we encourage you to get involved.

A. Acknowledgements

This section is non-normative.

The editors thank all members of the OpenActive Community Group for their contributions.

B. References

B.1 Normative references

[JSON-LD]
JSON-LD 1.0. W3C. W3C Recommendation. URL: https://www.w3.org/TR/json-ld/