CoverageJSON schema mismatched with OpenAPI 3.1 document

[havardf]

The OpenAPI 3.1.1 document references a CoverageJSON JSON-schema document via url, like $ref: https://covjson.org/schema/dev/coveragejson.json in core/standard/openapi/oas31/responses/queries/200.yaml.

However, this causes a problem with the resulting bundled OpenAPI document.

OpenAPI 3.1 base their schema on JSON Schema Specification Draft 2020-12, as far as I can tell. But https://covjson.org/schema/dev/coveragejson.json is based on http://json-schema.org/draft-07/schema, which is an older version of JSON-Schema. And it uses terms that seem to no longer validate, like dependencies (which was deprecated in 2019 as far as I understand). This results in an invalid openapi document for EDR. At least that is what I am seeing when I bundle this with redocly-cli and then validate the resulting document.

Is it possible to reference a schema for CoverageJSON which is updated to the same JSON-schema version that OpenAPI 3.1.1 uses?

[chris-little]

@jonblower FYI

[chris-little]

@jonblower I think we may need to have a Corrigendum, or new version of CoverageJSON, as the OGC APIs, including EDR are busy adding support for OpenAPI V3.1.
There are advantages to using OpenAPI V3.1 as it is more compatible with JSON Schema rather than YAML.
I will discuss with @m-burgoyne and @havardf to see how much work is involved.

[jonblower]

I need to look at it more closely, but I think we can fix this just by rebuilding the schema against the new draft. I don't think it requires a change to the spec itself.

Looking at https://github.com/covjson/covjson-validator, it seems that we intentionally downgrade to draft-07 when we build the schema. Presumably at the time this was required for compatibility reasons, but probably this isn't required anymore.

[havardf]

I think the changes are quite small. From my quick look, it seemed to only be about replacing dependencies with dependentSchemas.

Might be some other stuff as well of course.

[jonblower]

Looking quickly at the source code, it looks like we already use dependentSchemas but it gets downgraded when we produce the draft-07 version, which we probably don't need to do anymore.

Are you able to test by building the bundled schema yourself (e.g. by running python -m tools.bundle_schema --out coveragejson.json as per https://github.com/covjson/covjson-validator)? If not I can see if I can generate one myself

[jonblower]

I was about to say that this issue probably belongs to the covjson-validator repo (https://github.com/covjson/covjson-validator/tree/main), but that made me wonder if we should move the schema to the same repository as the spec? From recent conversations it seems that the schema is considered part of the spec

[chris-little]

@jonblower That was part of the argument for having a V1.0.1 - we debated and agreed that a spec includes the schema, and the schema, not the spec text, is normative, and consequently 3 level versioning is required (Vmajor.minor.patch)

[chris-little]

@havardf @jonblower We can apply a quick fix to the draft OGC API-EDR V1.2 to point to the OGC version of CoverageJSON schemas rather than the community CovJSON repository. In the longer term, V1.0.1 of CoverageJSON would do the same.
Thoughts?

[chris-little]

@havardf @jonblower We can implement the schema build process when API-EDR Part 1 Core V1.2 is approved in the next few weeks, as part of the usual editorial changes before publication.
Other issues depends on OGC having an appropriate register available. I have asked @ghobona .

[havardf]

Sorry for not replying to this. If the OGC version of the coverageJson schema has the correct json schema version then I am happy :)

[chris-little]

EDR V1.2 has been updated to point to the CoverageJSON schema, but the schema in the validator repo needs to be upgraded. @jonblower to action.

[chris-little]

@jonblower @ghobona @havardf I have just looked in detail at the OGC CoverageJSON Schema and it still refers to dependencies and definitions rather than the updated dependentSchemas or $defs, and to JSON Schema Draft 7.
However, dependencies and definitions are discouraged but both are still maintained in the JSON meta-schema.
Upgrading to the later 2019 version of JSON Schema should not be difficult, but upgrading to 2020 is rather more significant as the definition of keyword items is changed significantly.
Can we discuss what the preferred options are?

[chris-little]

@jonblower @havardf @ghobona Can we easily migrate to JSON Schema 2020, as mandated by OpenAPI 3.1. We think we can easily migrate to the 2019 version, through the schema build process.
API-Features uses YAML not JSON Schema
API Connected systems use Draft-7
At the Community Group on 2026-03-11 we agreed this was appropriate for a Corrigendum, and there was enough flexibility in the OGC Schema repo to support various approaches. Guidance probably needed for the various API SWGs.