openactive / dataset-api-discovery Goto Github PK

View Code? Open in Web Editor NEW

0.0 4.0 0.0 632 KB

OpenActive Dataset API Discovery Specification

HTML 84.09% JavaScript 11.73% Shell 4.18%

dataset-publication specifications

dataset-api-discovery's Introduction

dataset-api-discovery

OpenActive Dataset API Discovery Specification (Editors Draft)

dataset-api-discovery's People

Contributors

Watchers

dataset-api-discovery's Issues

ID spoofing mitigation when using JSON-LD IDs

An ID prefix should be provided within the dataset site.

When a dataset site is used by a data user, the data user should check that they have no overlapping prefixes with other registered dataset sites (e.g. https://example.com/system1/ overlaps with https://example.com/system1/subsystem1).

The dataset site's own domain must also match the dataset site's ID prefix.

Additionally the the data user should check that all opportunity and offer IDs within the data feeds linked from the dataset site match the specified ID prefix.

This mitigates the risk of ID spoofing: where an attacker could impersonate another booking system by simply using their IDs.

Absolute Orders Feed URLs

We currently need to support absolute Orders Feed URLs:

The absolute URL of the Orders feed may be separately discoverable, independently of the Base URI, provided that such discovery is consistent with the Dataset-API-Discovery specification. If such an absolute URL is available, it must be used instead of the relative path defined within this specification.

from https://openactive.io/open-booking-api/EditorsDraft/#paths-and-verbs

Perhaps one for feedback as the Open Booking API implementations get underway...?

Differentiate between different types of feeds

Ensure that the feeds are described with enough detail for them to be automatically identified, using the metadata below for example:

https://github.com/openactive/data-models/blob/master/versions/2.x/meta.json#L9

Specifically consider how feeds of "CourseInstanceSubEvent" and "HeadlineEventSubEvent" can be differentiated in the metadata, when they both contain items of type "Event". Perhaps using the "identifier" in the above meta.json as the "kind", and including the "kind" also in the Dataset Site metadata?

Visual description of type hierarchy for current OpenActive Modelling specification:

Add an enumeration for "production" and "test" environments

Datasets are currently published from test and UAT environments (see http://visualiser.openactive.io/).

There is currently no way to distinguish between live data and test data.

The dataset site should include a flag (and ideally content in the HTML template too) that indicates that it represents a test environment.

Return pagination information in response

One of the practical difficulties of the harvesting model is knowing when harvesting can reasonably be expected to be complete.

The proposal here would be to include some pagination information in the response, e.g.

{
  "next": "https://opdt.service/someservice?afterTimestamp=2611788&afterId=12345",
  "totalItems" : "10000",
  "items": [{
    "..." : "..."
  }],
  "license": "https://creativecommons.org/licenses/by/4.0/"
}

In this example, the client is effectively on page 2 of a 200-page feed.

While of course it would not be possible for progress-tracking to be absolutely accurate (given the possibility of records being added during the harvesting process), nevertheless a rough indication would be given as to whether the harvesting process could be expected to last minutes, hours, or days; progress bars could be constructed; etc.

On the server side, the main additional requirement would be to run a COUNT query (for RDBs, at any rate) getting the total number of items that satisfy a query.

Status codes and feed listing

We should also take into account the following two scenarios:

Feed reference removed from the dataset site - that feed has gone and should no longer be harvested, but other feeds specified in the dataset site should continue to be harvested
The dataset site itself is returning a 404 - The publisher has unpublished their data, and all data relating to that publisher should be purged immediately, in case of GDPR breach or similar (Note some systems such as Gladstone are designed to return a 404 from the dataset site if a user presses the "disable open data feeds" button within their booking system, so this is by design)

5.4.2.3 Describing API Endpoints (schema:CreativeWork)

Should be schema:EntryPoint

Representing multiple feeds in schema.org

The way that multiple data feeds are currently being represented by early implementers has not been validated by schema.org.

A request was previously sent to the mailing list here: https://lists.w3.org/Archives/Public/public-schemaorg/2019Jan/0019.html

Property column should include namespace prefix and by hyperlinked

E.g. schema:conformsTo instead of just conformsTo (note that this term, as an example, is not yet available as it is pending schema PR, but that's ok)

`dataPublished` typo

dataPublished should be schema:datePublished

authenticationAuthority

Add oa:authenticationAuthority to WebAPI.

This property of type https://schema.org/URL should be defined as follows:

The location of the OpenID Provider or other relevant authentication authority that must be used to access the API.

For example:

https://auth.bookingsystem.com

Representing feature profiles of specifications

The Open Booking API allows includes a selection of optional features

conformsTo comes straight from DCAT v2, where it is a URL - so assume the same constraint exists, which might be enough to satisfy schema.org

Option 1 - profiles defined via certification

{
  "@context": "http://schema.org/",
  "@type": "Dataset",
  ...
  "bookingService": {
    "@type": "BookingService",
    "hasCredential": "https://openactive.io/openactive-test-suite/example-output/controlled/certification/"
  }
}

{
  "@context": "https://openactive.io/",
  "@type": "ConformanceCertificate",
  "@id": "https://openactive.io/openactive-test-suite/example-output/controlled/certification/",
  ...
  "featureImplemented": [
    {
      "@type": "Concept",
      "@id": "https://openactive.io/specification-features#dataset-site",
      "prefLabel": "Dataset Site",
      "inScheme": "https://openactive.io/specification-features"
    },
    ...
   ]
}

Pros:

Feature set is controlled in test suite and not in spec: easier to iterate
Clearer what ConformanceCertificate applies to

Cons:

No mode of feature assertion without a ConformanceCertificate

Option 2 - profiles asserted in dataset site

{
  "@context": "http://schema.org/",
  "@type": "Dataset",
  ...
  "accessService": {
    "@type": "WebAPI",
    ...
    "conformsTo": [
      "https://www.openactive.io/open-booking-api/1.0/#core-sessions",
      "https://www.openactive.io/open-booking-api/1.0/#core-facilities",
      "https://www.openactive.io/open-booking-api/1.0/#core-courses",
      "https://www.openactive.io/open-booking-api/1.0/#attendee-details",
      "https://www.openactive.io/open-booking-api/1.0/#approval-flow"
    ],
    "endpointDescription": "https://www.openactive.io/open-booking-api/1.0/swagger.json",
  }
}

Pros:

Feature assertion without a ConformanceCertificate

Cons:

Potential overloading of conformsTo for feature selection, also complicates conformsTo

Mapping to DCAT2

Noting a missing section: we agreed on a previous call that the spec should include a mapping to DCAT2, for completeness and to provide guidance for those looking to add both JSON-LD and DCAT markup to their site (which includes the OA supplied template format)

Options for describing APIs associated with Datasets

This proposal includes details of several alternative mechanisms for describing Web APIs related the open data sets. The focus of this discussion is on describing the Open Booking API.

schema:Action

Previous design iterations of this specification suggested the use of Action and a way of specifying various endpoints, as below. The idea was that each endpoint would indicate the next endpoint in the flow to call. As the number of specification features increased, it became increasingly apparent that this dynamic approach increased implementation complexity significantly. Additionally in reality implementers were unlikely to blindly follow dynamic URLs provided by API endpoints during each booking operation for security reasons.

To maintain flexibility in the endpoint paths, dynamic URLs must therefore be declared in a discovery document (e.g. at .wellknown, similar to OpenID Connect Discovery 1.0) or within the dataset site using potentialAction.

One dataset site based discovery approach would look as below - which is stretching the Action beyond its intended purpose given the number of endpoints - and essentially creating our own API description language, while there are many good alternatives (such as Open API) that already exist. Note that as this approach is not supported by Google for SEO, we would also likely be required to provide a JSON-LD WebAPI in the markup of the dataset site.

{
  "@type": "Dataset",
  ...
  "potentialAction": {
    "@type": "OpenBookingAction",
    "target": [
      {
        "@type": "EntryPoint",
        "urlTemplate": "https://example.com/api/order-quote-templates/{uuid}",
        "encodingType": ["application/vnd.openactive+jsonld; model=2.0, booking=1.0"],
        "httpMethod": "PUT"
      },
      {
        "@type": "EntryPoint",
        "urlTemplate": "https://example.com/api/order-quotes/{uuid}",
        "encodingType": ["application/vnd.openactive+jsonld; model=2.0, booking=1.0"],
        "httpMethod": "PUT"
      },
      {
        "@type": "EntryPoint",
        "urlTemplate": "https://example.com/api/orders/{uuid}",
        "encodingType": ["application/vnd.openactive+jsonld; model=2.0, booking=1.0"],
        "httpMethod": "PUT"
      },
      {
        "@type": "EntryPoint",
        "urlTemplate": "https://example.com/api/orders/{uuid}",
        "encodingType": ["application/vnd.openactive+jsonld; model=2.0, booking=1.0"],
        "httpMethod": "PATCH"
      },
      {
        "@type": "EntryPoint",
        "urlTemplate": "https://example.com/api/orders/{uuid}",
        "encodingType": ["application/vnd.openactive+jsonld; model=2.0, booking=1.0"],
        "httpMethod": "DELETE"
      },
      ...
    ],
    "supportingData": {
      "@type": "DataFeed",
      "distribution": [
        {
          "@type": "DataDownload",
          "name": "Order",
          "additionalType": "https://schema.org/Order",
          "encodingFormat": ["application/vnd.openactive.booking+json; version=1.0"],
          "contentUrl": "https://example.com/api/feeds/offers"
        }
      ]
    }
  }
}

schema:WebAPI

We have contributed to the current discussion on WebAPI, based on the current WADG0001 WebAPI type extension specification, considering additional suggested amendments applied, and the new Data Catalog Vocabulary (DCAT) - Version 2 - which has suggested bringing WebAPI more inline with DCAT v2. This would effectively make it a superset of the DCAT v2 functionality, which is also useful for simplifying implementation.

The focus here is on a OpenAPI / Swagger definition of the endpoints available at a specific base URL. If this Swagger document was to be maintained centrally by OpenActive, the implementer would be able to vary the base URL, however the names of the endpoints would be fixed. This lends itself much less to a "discovery-based" approach than the Hydra and Action alternatives above.

{
  "@context": "http://schema.org/",
  "@type": "Dataset",
  ...
  "accessService": {
    "@type": "WebAPI",
    "name": "Google Knowledge Graph Search API",
    "description": "The Knowledge Graph Search API lets you find entities in the Google Knowledge Graph. The API uses standard schema.org types and is compliant with the JSON-LD specification.",
    "documentation": "https://developers.google.com/knowledge-graph/",
    "termsOfService": "https://developers.google.com/knowledge-graph/terms",
    "logo": "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png",
    "license": "https://creativecommons.org/licenses/by/3.0/",
    "provider": {
      "@type": "Organization",
      "name": "Google Inc.",
      "contactPoint": [
        {
          "@type": "ContactPoint",
          "name": "Google",
          "url": "https://google.com"
        }
      ],
    },
    "version": [
      "1.0.0"
    ],
    "endpointURL": [
      {
        "@type": "EntryPoint",
        "url": "https://example.com/api/openbooking/",
        "contentType": "application/json"
      }
    ],
    "apiTransport": "HTTPS",
    "conformsTo": [
      "https://www.openactive.io/open-booking-api/1.0/#core",
      "https://www.openactive.io/open-booking-api/1.0/#attendee-details",
      "https://www.openactive.io/open-booking-api/1.0/#approval-flow"
    ],
    "endpointDescription": [
      {
        "@type": "EntryPoint",
        "contentType": "application/vnd.oai.openapi+json;version=2.0",
        "url": "https://www.openactive.io/open-booking-api/1.0/swagger.json"
      },
    ],
    "potentialAction": [
      {
        "@type": "ConsumeAction",
        "name": "API Client Registration",
        "target": "https://exampleforms.com/get-me-an-api-access-key"
      }
    ]
  }
}

DCAT v2

The recently published Data Catalog Vocabulary (DCAT) - Version 2 appears to cover OpenActive's own discovery requirements comprehensively, and seems to be designed with standards-compliant APIs in mind, though it is missing properties from WebAPI that could still be useful for SEO. We have suggested ways that WebAPI can align more closely to this, to give it the power of both.

This approach is inline with the WebAPI suggestion, having a fixed Swagger definition of the endpoints paths available at a variable base URL. The implementer of a particular standard specification can therefore vary the base URL, however the names of the endpoints are mandatory, unless they were to create a new amended copy of the Swagger document - which would be inefficient and overly complex compared to the Action approaches above.

Using DCAT v2:

dcat:accessService ordinarily links the Distribution to the DataService, so we would need to repurpose it here to link the Dataset to the DataService.
dct:conformsTo can be used to reference the specific implementation of the specification, and could be used to indicate supported profiles too. The example below includes profiles only, as these also indicate the version of the specification.
dct:accessRights describes the terms of access
dcat:endpointDescription an be used to contain the Open API / Swagger definition of the API, describing individual endpoints from the specified base URL.
dcat:endpointURL describes the "The root location or primary endpoint of the service", which is recommending that a base URL be specified.
dcat:landingPage the URL to obtain access to the API via e.g. a web form (note dcat:accessURL is not appropriate for for dct:DataService, as it matches the property-chain dcat:accessService/dcat:endpointURL).

Example

{
  "@type": "Dataset",
  ...
  "dcat:accessService": {
    "@type": "dct:DataService",
    "dct:title": "Open Booking API for Acme Leisure",
    "dct:description": "An API that provides access to make bookings for sessions and facilities, conforming to Open Booking API 1.0.",
    "dcat:landingPage": "https://exampleforms.com/get-me-an-api-access-key",
    "dcat:endpointDescription": "https://www.openactive.io/open-booking-api/1.0/swagger.json",
    "dct:conformsTo": [
      "https://www.openactive.io/open-booking-api/1.0/#core",
      "https://www.openactive.io/open-booking-api/1.0/#attendee-details",
      "https://www.openactive.io/open-booking-api/1.0/#approval-flow"
    ],
    "dcat:endpointURL": "https://example.com/api/openbooking/"
  }
}

Also note that the publisher, keyword and language properties could be duplicated from the Dataset to aid SEO

SEO Note

To ensure we create maximum exposure for Open Booking API implementations in terms of SEO and data catalogues, we will likely want to include JSON-LD WebAPI in the markup, as well as DCAT v2 terms embedded in the HTML using RDFa, as the current Dataset Sites do.

Gaps still to be filled

Note the above does not allow for referencing Dataset / WebAPI certifications, or for stating profiles of opportunity data.

OpenActive Certified / Open Data Certificates

For describing certificates relating to a Dataset, for example "Open Data Certificate" or "OpenActive Certified", could we propose in schema.org that they add schema:Dataset to the domain of schema:hasCredential? Then also propose a rename of schema:educationalLevel to a superseding, more generic pending:credentialLevel?

Example below:

{
  "@context": "http://schema.org/",
  "@type": "Dataset",
  "name" : "British Cycling Let's Ride Sessions",
  "url": "http://data.letsride.co.uk/",
  ...
  "hasCredential": {
    "@type": "EducationalOccupationalCredential",
    "name": "Open Data Certificate - Silver level",
    "description": "Open Data Certificate is a free online tool developed and maintained by the Open Data Institute, to assess and recognise the sustainable publication of quality open data. It assess the legal, practical, technical and social aspects of publishing open data using best practice guidance. This data has achieved Silver level on 15 July 2016 which means extra effort went in to support and encourage feedback from people who use this open data.",
    "url": "https://certificates.theodi.org/en/datasets/214126/certificate",
    "dateCreated": "2016-07-04",
    "dateModified": "2016-07-15",
    "validFor": "P5Y",
    "credentialLevel": {
      "@type": "DefinedTerm",
      "name": "Silver level",
      "description": "This data has achieved Silver level which means extra effort went in to support and encourage feedback from people who use this open data.",
      "termCode": "SILVER"
    },
    "credentialCategory": {
      "@type": "DefinedTerm",
      "name": "Open Data Certificate",
      "description": "Open Data Certificate is a free online tool developed and maintained by the Open Data Institute, to assess and recognise the sustainable publication of quality open data. It assess the legal, practical, technical and social aspects of publishing open data using best practice guidance.",
      "termCode": "ODI-CERT"
    },
    "recognizedBy": {
      "@type": "Organization",
      "name": "Open Data Institute",
      "url": "https://theodi.org/"
    }
  }
}

Would we also need schema:hasCredential to apply to the WebAPI? Do we have separate certification for discovery (i.e data quality) and booking (i.e. capability)?

Data quality profiles for datasets

Could we use the same DCAT approach for Dataset to include dct:conformsTo? So we recommend to schema.org that they include schema:Dataset in the domain of pending:conformsTo (assuming they accept it for WebAPI?).

{
  "@context": "http://schema.org/",
  "@type": "Dataset",
  ...
  "conformsTo": [
    "https://www.openactive.io/modelling-opportunity-data/2.0/#core-sessions"
  ]
}

Questions

Thoughts very welcome on the following:

Discovery vs defined endpoints with a base URL

The initial thoughts gathered from the OpenActive W3C Community Group were that allowing flexibility for the name of each endpoint within a Web API to vary per-implementation, and for such endpoints to be discoverable, would be good practice and avoid being overly prescriptive for implementers. This follows patterns such as OpenID Connect Discovery 1.0 and OAuth 2.0 Authorization Server Metadata, that allow each endpoint URL to be fully configurable.

Implementation experience has shown that in practice for the Open Booking API such flexibility is both (i) not desired by booking system implementers, who often request a recommended naming approach; and (ii) complicates tooling and client design as an extra level of indirection and flexibility needs to exist in the data contract.

Prescribed endpoint paths would mean that we can use schema:WebAPI and dcat:DataService with e.g. a standard Open API / Swagger document, rather than discovery documents that needs to be interrogated and a client configured (automatically or manually) for each booking system a broker connects to.

For booking system providers: does anyone have an objection to Open Booking 1.0 using prescribed endpoint paths within a base URL, to simplify implementation?

Beta implementation

Given the current inconsistent state of the extensions to schema:WebAPI, and the additional work required for both implementers and tooling to allow for varying endpoint URLs, the simplest approach for early implementations of the Open Booking API appears to be to use the more developed DCAT v2 approach, using terms from the WebAPI where they have already been promoted to pending.schema.org. Hence this proposal recommends the following be used for beta implementations in the first instance:

  "@context": "http://schema.org/",
  "@type": "Dataset",
  ...
  "accessService": {
    "@type": "WebAPI",
    "name": "Google Knowledge Graph Search API",
    "description": "The Knowledge Graph Search API lets you find entities in the Google Knowledge Graph. The API uses standard schema.org types and is compliant with the JSON-LD specification.",
    "documentation": "https://developers.google.com/knowledge-graph/",
    "termsOfService": "https://developers.google.com/knowledge-graph/terms",
    "endpointURL": "https://example.com/api/openbooking/",
    "conformsTo": [
      "https://www.openactive.io/open-booking-api/1.0/#core-sessions",
      "https://www.openactive.io/open-booking-api/1.0/#core-facilities",
      "https://www.openactive.io/open-booking-api/1.0/#core-courses",
      "https://www.openactive.io/open-booking-api/1.0/#attendee-details",
      "https://www.openactive.io/open-booking-api/1.0/#approval-flow"
    ],
    "endpointDescription": "https://www.openactive.io/open-booking-api/1.0/swagger.json",
    "landingPage": "https://exampleforms.com/get-me-an-api-access-key",
  }
}

This metadata can easily be expanded into the proposed full schema:WebAPI once agreed, by updating the library that does the transformation - without any additional work required by implementers.

`publisher` vs `creator` vs ? / certificates and feature lists

Problem

We need to align how we're representing organizations that are related to a dataset with Google's expectations for the purposes of SEO.

The current draft data model for Dataset API Discovery includes:

  "publisher": {
    "@type": "Organization",
    "name": "Fusion Lifestyle",
    "description": "Fusion Lifestyle was established in April 2000 ...",
    "email": "[email protected]",
    "legalName": "Fusion Lifestyle",
    "logo": {
      "@type": "ImageObject",
      "url": "https://res.cloudinary.com/gladstone/image/upload/fusion-lifestyle-live/ydokan4mlia7zigqd79d"
    },
    "url": "https://www.fusion-lifestyle.com/"
  },
  "bookingService": {
    "@type": "BookingService",
    "name": "Gladstone360",
    "url": "https://www.gladstonesoftware.co.uk",
    "softwareVersion": "3.0.2"
  },

bookingService is a property in the OpenActive namespace, and is not recognised by Google. It is also not clear whether the publisher property is being used correctly in this context.

Considerations

Google's Structured Data Documentation

Google's Structured Data Documentation recommends the use of the property creator to represent the "The creator or author of this dataset", and does not provide specific references for other properties (though points to schema.org for more information).

schema.org

schema.org includes several options for attibution of the roles of organizations relating to a schema:Dataset:

creator - The creator/author of this CreativeWork
maintainer - A maintainer of a Dataset
publisher - The publisher of the creative work.
sourceOrganization
and others

Existing OpenActive dataset sites

The dataset site text reads:

This data is owned by <a href="{{publisher.url}}">{{publisher.legalName}}</a> and is licensed under the Creative Commons Attribution Licence (CC-BY v4.0) for anyone to access, use and share; using attribution "<a href="{{url}}"><span>{{publisher.name}}</span></a>".

Platform: <a href="{{bookingService.url}}">{{bookingService.name}} {{bookingService.softwareVersion}}</a>.

Note that single database systems generally set bookingService to match publisher, as they are the same.

Proposal

Note this proposal doesn't consider maintainer, which could be useful to include within the JSON-LD as a duplicate of creator (if set)?

Multiple database systems

For multiple database systems, where there is one dataset site per activity provider:

creator - The activity provider
publisher - The booking system

This data is owned by <a href="{{creator.url}}">{{creator.legalName}}</a> and is licensed under the Creative Commons Attribution Licence (CC-BY v4.0) for anyone to access, use and share; using attribution "<a href="{{url}}"><span>{{creator.name}}</span></a>".

Platform: <a href="{{publisher.url}}">{{publisher.name}} {{publisher.softwareVersion}}</a>.

Single database systems

For single database systems, where there is one dataset site that contains data from multiple activity providers:

publisher - The booking system

This data is owned by <a href="{{publisher.url}}">{{publisher.legalName}}</a> and is licensed under the Creative Commons Attribution Licence (CC-BY v4.0) for anyone to access, use and share; using attribution "<a href="{{url}}"><span>{{publisher.name}}</span></a>".

(Note in this proposal the "Platform" reference is removed from the HTML for Single database systems)

Implementation note

We need to ensure the embedded DCAT markup reflects this change.

DataCatalog

A DataCatalogCollection should be defined, that contains a list of data catalogs

{
   "@context": "https://openactive.io/",
   "@type": "DataCatalogCollection",
   "@id": "https://openactive.io/data-catalogs/data-catalog-collection.jsonld",
   "name": "Collection of all data catalogs recognised as compliant by OpenActive",
   "hasPart": [
      "https://opendata.leisurecloud.live/api/datacatalog",
      "https://openactivedatacatalog.legendonlineservices.co.uk/api/DataCatalog",
      "https://openactive.io/data-catalogs/singular.jsonld"
   ],
   "datePublished": "2020-02-20T08:51:54+00:00",
   "publisher": {
      "@type": "Organization",
      "name": "OpenActive",
      "url": "https://www.openactive.io/"
   },
   "license": "https://creativecommons.org/licenses/by/4.0/"
}

Note for OpenActive's use, in the above example, https://openactive.io/data-catalogs/singular.jsonld would be separately defined as a data catalogue of miscellaneous datasets using https://schema.org/DataCatalog as normal.

Unclear MIME type

The MIME-type of this JSON object must be application/ld+json., though it is not clear what this means in context. Suggest this references the HTML script tag, and that the worked example includes the HTML script tag embed?

Full "Early release" JSON-LD example of DataSet

The below JSON-LD snippet is an example of the output from the current "early release" OpenActive tooling, for reference:

{
  "@context": [
    "https://schema.org/",
    "https://openactive.io/"
  ],
  "@type": "Dataset",
  "@id": "https://example.bookingsystem.com/openactive/",
  "name": "Better Sessions and Facilities",
  "description": "Near real-time availability and rich descriptions relating to the sessions and facilities available from Better",
  "accessService": {
    "@type": "WebAPI",
    "name": "Open Booking API",
    "description": "API that allows for seamless booking experiences to be created for sessions and facilities available from Better",
    "conformsTo": [
      "https://www.openactive.io/open-booking-api/EditorsDraft/"
    ],
    "documentation": "https://developer.openactive.io/go/open-booking-api",
    "endpointDescription": "https://www.openactive.io/open-booking-api/EditorsDraft/swagger.json",
    "endpointUrl": "https://example.bookingsystem.com/api/openbooking/",
    "url": "https://exampleforms.com/get-me-an-api-access-key",
    "termsOfService": "https://example.bookingsystem.com/terms"
  },
  "backgroundImage": {
    "@type": "ImageObject",
    "url": "https://data.better.org.uk/images/bg.jpg"
  },
  "bookingService": {
    "@type": "BookingService",
    "name": "AcmeBooker",
    "softwareVersion": "2.0",
    "url": "https://acmebooker.example.com/",
    "hasCredential": "https://openactive.io/openactive-test-suite/example-output/controlled/certification/"
  },
  "dateModified": "2020-04-23T14:48:13+01:00",
  "datePublished": "2019-01-14T00:00:00+00:00",
  "discussionUrl": "https://github.com/gll-better/opendata",
  "distribution": [
    {
      "@type": "DataDownload",
      "name": "ScheduledSession",
      "additionalType": "https://openactive.io/ScheduledSession",
      "contentUrl": "https://example.bookingsystem.com/feeds/scheduled-sessions",
      "encodingFormat": "application/vnd.openactive.rpde+json; version=1",
      "identifier": "ScheduledSession"
    },
    {
      "@type": "DataDownload",
      "name": "SessionSeries",
      "additionalType": "https://openactive.io/SessionSeries",
      "contentUrl": "https://example.bookingsystem.com/feeds/session-series",
      "encodingFormat": "application/vnd.openactive.rpde+json; version=1",
      "identifier": "SessionSeries"
    },
    {
      "@type": "DataDownload",
      "name": "FacilityUse",
      "additionalType": "https://openactive.io/FacilityUse",
      "contentUrl": "https://example.bookingsystem.com/feeds/facility-uses",
      "encodingFormat": "application/vnd.openactive.rpde+json; version=1",
      "identifier": "FacilityUse"
    },
    {
      "@type": "DataDownload",
      "name": "Slot for FacilityUse",
      "additionalType": "https://openactive.io/Slot",
      "contentUrl": "https://example.bookingsystem.com/feeds/facility-use-slots",
      "encodingFormat": "application/vnd.openactive.rpde+json; version=1",
      "identifier": "FacilityUseSlot"
    }
  ],
  "documentation": "https://docs.acmebooker.example.com/",
  "inLanguage": [
    "en-GB"
  ],
  "keywords": [
    "Sessions",
    "Facilities",
    "Activities",
    "Sports",
    "Physical Activity",
    "OpenActive"
  ],
  "license": "https://creativecommons.org/licenses/by/4.0/",
  "publisher": {
    "@type": "Organization",
    "name": "Better",
    "description": "Established in 1993, GLL is the largest UK-based charitable social enterprise delivering leisure, health and community services. Under the consumer facing brand Better, we operate 258 public Sports and Leisure facilities, 88 libraries, 10 children’s centres and 5 adventure playgrounds in partnership with 50 local councils, public agencies and sporting organisations. Better leisure facilities enjoy 46 million visitors a year and have more than 650,000 members.",
    "email": "[email protected]",
    "legalName": "GLL",
    "logo": {
      "@type": "ImageObject",
      "url": "http://data.better.org.uk/images/logo.png"
    },
    "url": "https://www.better.org.uk/"
  },
  "schemaVersion": "https://www.openactive.io/modelling-opportunity-data/2.0/",
  "url": "https://example.bookingsystem.com/openactive/"
}

Consider .well-known for discovery

.well-known could be used in addition to the dataset site to make it easy for a specific provider to advertise booking capabilities?

softwareVersion

softwareVersion is defined incorrectly. Should be "Version of the software application", and should be on the schema:SoftwareApplication (instead of the version) and not on the Dataset

version should also be removed from WebAPI

Consistency of @context

Following a discussion with @thill-odi and @nathansalter, it appears that the spec should include a note that:

It is common practice is to reference https://schema.org without a trailing / within @context. However to be consistent with the OpenActive Modelling Opportunity Data specification, which uses the full URI of https://openactive.io/ (including a path as per RFC 3986), the specification requires the schema.org context to be referenced with a trailing slash, i.e. https://schema.org/.

  "@context": [
    "https://schema.org/",
    "https://openactive.io/",
    "https://openactive.io/ns-beta"
  ],

This approach was commended as Google can handle either, and including a / is more technically correct (ref).

5.4.2.2 Supporting Booking (schema:webAPI)

5.4.2.2 Supporting Booking (schema:webAPI)

should be

5.4.2.2 Supporting Booking (schema:WebAPI)

Worked example does not include all properties

Worked example does not include all properties, e.g. it is missing bookingService