search

openactive / dataset-api-discovery

OpenActive Dataset API Discovery Specification
0 stars 0 forks source link

Representing feature profiles of specifications #15

Open nickevansuk opened 3 years ago

nickevansuk commented 3 years ago

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:

Cons:

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:

Cons:

nickevansuk commented 3 years ago

Following the W3C call of 2020-09-09: on reflection, one issue with embedding the features list in the Dataset Site (any iteration of Option 2, which does not overload conformsTo) is that it duplicates it across all Dataset Sites where it is actually related only to the product. This greatly increases the complexity of the Dataset Site; a complexity which is distributed across all publishing systems, and multiplied by the number of languages supported by the OpenActive tooling (PHP, Ruby, .NET, etc).

For the benefit of publishers and to reduce tooling maintenance overall, this should be simplified, and the complexity centralised into the OpenActive Test Suite, which will be run by all publishers anyway, and is limited to a single codebase. Hence, a specific Conformance Certificate is used to retrieve the features available in a particular implementation (or perhaps a version of an implementation, as e.g. a certificate may exist for each version of an on-premise solution).

This allows us to go with Option 1 above, and for this specification to define a more general hasCredential property, under BookingService, which can be described as "a human and machine-readable certification file that asserts the service’s conformance to established standards", to reference the relevant OpenActive Conformance Certificate. This could have a range of schema:EducationalOccupationalCredential to decouple it from the implementation of the certificates.

To facilitate this, the details of OpenActive Conformance Certification has been moved into a separate repository and vocabulary: https://github.com/openactive/conformance-certification/issues/1#issuecomment-693474042. This means that it is still documented and machine-readable for the benefit of data users while having minimal impact on publishers.

nickevansuk commented 1 year ago

To note for future discussion, a potential third way here could be to separate the feature list as a specific machine-readable file. This does add more complexity however, as it needs to be hosted, generated, and updated separately.

Consideration of this is perhaps best left until we are at a scale sufficient to test the utility of such a file.

{
  "@context": "http://schema.org/",
  "@type": "Dataset",
  ...
  "bookingService": {
    "@type": "BookingService",
    "hasCredential": "https://openactive.io/openactive-test-suite/example-output/controlled/certification/",
    "implementsFeatures": "https://openactive.io/openactive-test-suite/example-output/controlled/certification/features.json"
  }
}
{
  "@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"
    },
    ...
   ]
}
{
  "@context": "https://openactive.io/",
  "@type": "ConformanceCertificate",
  "@id": "https://openactive.io/openactive-test-suite/example-output/controlled/certification/",
  "name": "OpenActive Conformance Certificate for AcmeBooker",
  "description": "This conformance certificate has been produced automatically from the OpenActive Test Suite.",
  "dateCreated": "2020-07-04T18:49:47Z",
  "validFor": "P3M",
  "featureImplemented": [
    {
      "@type": "Concept",
      "@id": "https://openactive.io/specification-features#dataset-site",
      "prefLabel": "Dataset Site",
      "inScheme": "https://openactive.io/specification-features"
    },
    {
      "@type": "Concept",
      "@id": "https://openactive.io/specification-features#availability-check",
      "prefLabel": "Availability Checking",
      "inScheme": "https://openactive.io/specification-features"
    },
    {
      "@type": "Concept",
      "@id": "https://openactive.io/specification-features#simple-book-free-opportunities",
      "prefLabel": "Simple Booking of free opportunities",
      "inScheme": "https://openactive.io/specification-features"
    }
  ],
  "featureNotImplemented": [],
  "opportunityTypeImplemented": [
    "ScheduledSession"
  ],
  "associatedMedia": {
    "@type": "MediaObject",
    "contentUrl": "data:application/octet-stream;base64,UEsDBAoAAAAAADeW5FAAAAAAAAAAAAAAAAAJAA..."
  },
  "awardedTo": {
    "@type": "BookingService",
    "name": "AcmeBooker",
    "softwareVersion": "2.0",
    "url": "https://acmebooker.example.com/"
  },
  "recognizedBy": {
    "@type": "Organization",
    "name": "OpenActive",
    "url": "https://www.openactive.io/"
  }
}