Use consistent meta vocabulary and structure to schema.org

[nickevansuk]

The OpenActive specification is currently defined using 4 divergent combinations of meta vocabularies:

• RDFS / meta.schema.org = schema.org
• RDFS / owl = OpenActive namespace
• RDFS / schema.org / XSD = extensions
• Custom = OpenActive models

Although most of these are behind the scenes, as the Extensions vocabulary is included in the candidate spec it becomes subject to breaking change versioning.

Polymorphic schema:domainIncludes/schema:rangeIncludes vs monomorphic rdfs:domain / rdfs:range

Although schema.org's "domainIncludes" and "rangeIncludes" were not designed for wider use, they do remove the need to add additional "wrapper" types e.g. "Agent" to encompass both "Organization" and "Person", which has a direct impact on the modelling approach which schema.org takes, and which OpenActive is emulating.

Additionally any implementor attempting to use the machine readable namespaces will need to be able to parse schema:domainIncludes and schema:rangeIncludes as the majority of OA terms are actually in schema.org. It makes it easier for all if we are consistent in our use of these across namespaces.

Potential Solution

In order to keep the implementation here as lean as possible, suggest we keep it as close to schema.org as possible to ensure it's extensible in all the ways that the current schema.org implementation is (which allows for organic use / people to pick this up and run with it). This also means that we don't need to worry about any constraints that a divergent or more simplified approach would create on future versions / any breaking changes this would potentially create down the line.

Hence I propose that we standardise on using "domainIncludes" and "rangeIncludes" within OpenActive, and use the other properties as schema.org has done, to keep a modelling approach that is consistent with schema.org, as we have done elsewhere. This would require an update to OpenActive's own namespace, and also the extension property example in the specification.

A new namespace has been defined https://openactive.io/extension (see https://github.com/openactive/extensions for the JSON-LD context), which should also be used as part of the JSON-LD file that defines OpenActive's own namespace.

Side note: This could also be renamed https://openactive.io/meta or indeed https://meta.openactive.io/ in line with schema.org?

Hence the extension property examples in the specification should be updated to include structures that match the following example.

Note that the use of "type" and "id" will be familiar to existing OpenActive implementors

{
  "@context": [
    "https://openactive.io/extension",
    { "beta": "https://openactive.io/ns-beta#" }
  ],
  "@graph": [
    {
      "id": "beta:specialRequirements",
      "type": "Property",
      "label": "Special Requirements",
      "comment": "List of related special requirements from a controlled vocabulary.",
      "domainIncludes": [ "schema:Event" ],
      "rangeIncludes": [ "skos:Concept" ]
    }
  ]
}

For a more extensive example, see https://github.com/openactive/ns-beta/blob/master/beta.jsonld.

[ldodds]

Agree with aligning with modelling approach used in Schema.org. This isn't a critical issue that we need to resolve for 2.0 though. (And I'm not clear what the new namespace is for).

Moving this to backlog as requires further discussion.

[nickevansuk]

Great. The extensions example in 2.0 currently doesn't align with Schema.org, so this should be removed or updated to the above.

The new namespace is a meta namespace to make the JSON-LD for defining an extension namespace easier for publishers (https://www.openactive.io/extensions/extensions.jsonld), having it as a separate namespace allows it to be used for defining the main OpenActive namespace too (so it's a kind of bootstrap namespace)

I would suggest putting the meta stuff in the main OA namespace, but not sure we'll reuse the RDFS terms "label" and "comment", or the RDF "Property", or even "domainIncludes" and "rangeIncludes" anywhere outside of namespace definitions, so perhaps it's good to be clear what's legal in each scenario i.e. the JSON-LD file should either be defining an extension (using e.g. "@context": "https://meta.openactive.io/") or contain opportunity data ("@context": "https://openactive.io/") but not both.

This also helps us validate both files.

[nickevansuk]

Adding label back for example resolution above

[nickevansuk]

Also noting here, I've created a documentation generator based on the schema.org JSON-LD format (exactly the same, just simplified using Compact IRIs): https://github.com/openactive/extension-documentation-generator.

We can use this for documenting all defined extensions from existing data publishers, along with the beta namespace.

[nickevansuk]

This part of the spec is being linked from the validator and the example is still misleading, as we've agreed on aligning with modelling approach used in Schema.org.

This is going to cause issues with implementors and needs to be fixed, happy to do it.

[nickevansuk]

Reopening for discussion on this. Fix that automatically closed this was to remove the example from the spec to enable further discussion