Part 5: Improve flexibility and avoid local solutions that reduce interoperability

[rob-metalinkage]

The principle of annotation JSON schemas to provide operationally useful metadata is a good one.

There are a few issues with the current proposal

The first is that its a OGC specific approach for a general problem. COSI has been investigating this in detail with JSON schema, OpenAPI and JSON-LD technical committees and working groups - there is interest and expectation a general solution to semantic annotation (links to element definitions) will be addressed at some point.

1. a well-used standard for semantic annotation exists in the form of JSON-LD. It does have challenges with combining sub-schemas - hence work with the JSON schema lead author to review options, and implement a solution. Note there is tooling available for JSON-LD annotations, and now support tooling for compiling aggregate JSON-LD and semantic schema annotations from these. This is conceptually compatible with the proposed specification - but uses the tags x-jsonld-id and x-jsonld-type (as recommended by the experts consulted)

2. The current solution is incompatible with the direct reuse of existing schemas as payloads.

3. Existing schemas may already (and increasingly will) have JSON-LD mappings available - this proposal in its current form would require redundant information in publication of duplicate schemas with no added value.

• an example of using an existing schema to support semantic annotation of a Feature is at https://ogcincubator.github.io/bblocks-examples/bblock/ogc.bbr.examples.feature.externalSchema
• note the schema annotation is generated automatically to build the aggregate JSON-LD context but is not required to be used at run-time - only standard JSON-LD is needed.

Which leads to the biggest issue - as "Part 5" it suggests this is the only way schemas can be done, rather than a possible option. As an option it will require specialised tooling.

As a starting point, a "separation of concerns" should be applied to separate out the semantic annotation components from the other API-centric components - and the solution should be left open for further consideration of standardised approaches support by tooling. Possibly the semantic annotation could be published as a separate, optional, approach - consistent with the fact that any approach now will likely be a temporary workaround pending development of an industry-standard approach supported by common tooling.

It also feels that the "x-ogc-unit" aspect should also be factored out.

By simply adopting x-jsonld-id as the annotation tag, the OGC Building Blocks composer provides immediately available tooling to generate compatible schemas. Note that the Building Blocks tooling could also be extended to allow a simplified "schema annotation recipe" to be used to inject other tags such as "x-ogc-role" into existing schemas automatically, allowing specifications to use existing schemas, but compiling this form if required.