Validate all examples

[rob-metalinkage]

See #308 for an example of need for this.

Set up automated validation of examples to avoid this problem.

Contact OGC COSI staff for assistance if required.

OGC Building Blocks templates use a validation pipeline available from https://github.com/opengeospatial/bblocks-postprocess

This could be directly applied or adapted to use the existing repository, or a new OGC building blocks repository set up as a wrapper for all normative and informative content to perform validation and provide an opportunity to undertake further automation such as exercising mappings to other schemas.

[pvretano]

30-OCT-2023: JSON-FG has a script that validates all JSON examples; we will steal it for Records too. @tomkralidis will look into it.

[tomkralidis]

FYI this needs to wait until core/openapi/ogcapi-records-1.yaml is refactored/valid (note that we have discussed implementing the same approach as in OGC API - Coverages).

[pvretano]

SWG meeting 11-DEC-2023: @pvretano will endeavour to validate core/openapi/ogcapi-records-1.yaml before the next SWG meeting so that @tomkralidis can complete his modifications.

[tomkralidis]

@pvretano is core/openapi/ogcapi-records-1.yaml up to date so that I can finish the examples?

[kalxas]

I have merged the above pull request so we can move forward

[tomkralidis]

2024-01-05: I am working on the CI, pending updates to the OpenAPI schema setup (to be discussed at SWG 2024-01-08 meeting.

[tomkralidis]

I took another look at this today. There are a few issues:

• core/examples/json: some JSONs here are examples that can be directly validated against a JSON schema, others are partial snippets that are used in the document:

grep -R "include::" core/standard/| grep examples
core/standard//clause_7_building_blocks.adoc:include::../examples/json/keywords-themes.json[]
core/standard//clause_7_building_blocks.adoc:include::../examples/json/associations-simple-and-uri-template.json[]
core/standard//clause_7_building_blocks.adoc:include::../examples/json/templated-link-inline.json[]
core/standard//clause_7_building_blocks.adoc:include::../examples/json/templated-link-ref.json[]
core/standard//clause_7_building_blocks.adoc:include::../examples/json/record-collection.json[]
core/standard//clause_7_building_blocks.adoc:include::../examples/json/record.json[]
core/standard//clause_7_building_blocks.adoc:include::../examples/json/defaultSortOrder.json[]
core/standard//clause_7_building_blocks.adoc:include::../examples/json/sortables.json[]
core/standard//annex_common.adoc:include::../examples/json/landingPage.json[]
core/standard//annex_common.adoc:include::../examples/json/conformance.json[]
core/standard//annex_common.adoc:include::../examples/json/collections.json[]
core/standard//annex_common.adoc:include::../examples/json/collection.json[]
core/standard//clause_8_deployments.adoc:include::../examples/yaml/collection-extended.yaml[]

• https://github.com/opengeospatial/ogcapi-records/blob/master/core/examples/yaml/collection-extended.yaml : not an issue but I wonder whether we should remove (or convert to JSON for all instances)

• while the instance documents are JSON, the schemas themselves are YAML. I tried using check-jsonschema, however we need the schemas themselves to be in JSON. We could do this easily enough inside the CI but YAML schemas with $ref converted to JSON expected the resulting $ref's to be in JSON as well.

• if we want to validate partial examples, we need to validate them against the direct object (as a file) in tooling. Example: validating https://github.com/opengeospatial/ogcapi-records/blob/master/core/examples/json/landingPage.json against the OpenAPI examples because one cannot refer to a fragment in the tooling (i.e. "validate the landing page JSON example against the landing page definition within the OpenAPI example)

In the meantime, a CI is added in #340 that ensures the complete OpenAPI examples are always tested when a PR is issued the touches those files.

[kalxas]

Shall we close the issue or move it to the backlog?
In any case this should not block sending the specification to OAB anymore.

[pvretano]

22-JAN-2024: @pvretano will review the JSON examples to make sure they are consistent with the YAML schemas and close out this issue.