Conformance Certificates

[nickevansuk]

Background

In order to ensure that the level of quality of data published, and of API implementation can be verified, a conformance certification approach is generally taken within ecosystems.

For OpenActive, there are a number of details that are undefined, and that may change over time depending on the sustainability model:

• Should tests for such a certification be hosted, or run locally?
• Should results be stored and hosted centrally, or self-hosted?
• Should it be a free self-certification, or should it be independently verified with fees attached?
• Should there be a formal legal framework around it, or should it just be mechanism for implementers to demonstrate their conformance in a robust way to a non-technical audience?

Regardless of how such a certificate is obtained, the following properties of the certificate appear to be useful in all cases:

• The certificate must be machine-readable, so that it can be easily parsed by any data user / broker, or other interested party
• The certificate must be independently verifiable, including all test results
• The certificate must be automatically verifiable, given that many consumers of the certificates will not be experts in the API that they are assessing
• Continued conformance to the certificate must be guaranteeable via continuous integration, to ensure that certified systems are able to ensure their own conformance as part of BAU.

Additionally, to allow any type of decentralised model, the certificate must be sufficiently difficult to fake, such that any organisation that creates a fake certificate will have done so intentionally (a reputational risk) rather than just accidentally.

The OpenActive Test Suite's current implementation takes the lightest approach regarding the above, while making the move towards any more formal/centralised approach on any of the points above later fairly trivial:

• Tests are run locally (though the testing engine could easily be hosted)
• Results are self-hosted (though the same files could easily be hosted centrally)
• Free self-certification (though fees could easily be applied)
• There's no legal framework required (though could easily be introduced)
• The certificate is machine-readable, independently verifiable, automatically verifiable, generatable from CI, and difficult to fake

The current implementation currently exists primarily so that implementers have a simple and robust route to demonstrating conformance to a non-technical audience, while ensuring that the tooling is built and maintained with this capability in mind.

The current implementation of the certificate is a web page, that contains machine-readable JSON-LD, and an embedded Zip file of the results (see here for an example: https://openactive.io/openactive-test-suite/example-output/controlled/certification/).

Proposal

To cover the gap identified here, a specification should be provided that includes the provision to describe such a certification, on the basis that:

• Certification of some kind, however it is achieved, is likely to play a role in the OpenActive ecosystem going forward (as it has in other ecosystems)
• A model for such a certification can be derived from first principles given the existing OpenActive specifications, and appear independent to existence (or not) of any formal certification program.
• An initial reference implementation of such a certificate exists to validate these assumptions, and can be readily updated to match any model described here.

This proposal suggests the following structure to describe such a certification:

{
  "@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/"
  }
}

Modelling considerations for the above:

• oa:ConformanceCertificate could likely subclass schema:EducationalOccupationalCredential, which also includes schema:recognizedBy and schema:validFor, as well as schema:dateCreated and schema:associatedMedia (for the embedded Zip file) from schema:CreativeWork, and schema:name and schema:description from schema:Thing.
• oa:awardedTo represents which product has been certified (noting that an organisation may have multiple products, that have independent implementations).
• oa:featureImplemented, oa:featureNotImplemented and oa:opportunityTypeImplemented describe which features are implemented or not, and indicate that the product has been certified according to this assertion. They reference a controlled vocabulary, which could be defined outside the scope of the Dataset API Discovery specification (as where such features are defined could change over time - e.g. the CV could be part of the test suite and maintained along side it, or defined somewhere more formally)

Hence the modelling additions for this certification are fairly light.

[nickevansuk]

As this requirement of the Dataset API Discovery specification is currently only related to the certificate files generated by and validated by the OpenActive Test Suite, it has been moved into a separate repository and vocabulary (https://openactive.io/conformance-certification).

This vocabulary can evolve with the OpenActive Test Suite, and with implementation experience and more bandwidth available in the future, could be formalised into a full OpenActive specification.

Hence the machine-readable JSON-LD within the Conformance Certificate should be rendered as follows:

{
  "@context": [
    "https://openactive.io/",
    "https://openactive.io/conformance-certification"
  ],
  "@type": "cert: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",
  "cert: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"
    }
  ],
  "cert:featureNotImplemented": [],
  "cert:opportunityTypeImplemented": [
    "ScheduledSession"
  ],
  "associatedMedia": {
    "@type": "MediaObject",
    "contentUrl": "data:application/octet-stream;base64,UEsDBAoAAAAAADeW5FAAAAAAAAAAAAAAAAAJAA..."
  },
  "cert:awardedTo": {
    "@type": "BookingService",
    "name": "AcmeBooker",
    "softwareVersion": "2.0",
    "url": "https://acmebooker.example.com/"
  },
  "recognizedBy": {
    "@type": "Organization",
    "name": "OpenActive",
    "url": "https://www.openactive.io/"
  }
}