Move from OpenAPI 3.0 to OpenAPI 3.1

[m-burgoyne]

OpenAPI 3.1 was released in February 2021 and is fully aligned with JSON Schema, upgrading the OGC-EDR API to use OpenAPI schema 3.1 will remove the need to convert 3rd party data schemas that are based on the JSON Schema standard into a form compatible with OpenAPI 3.0.

As OpenAPI 3.1 has been the default standard for several years it will increasingly be the version that software tools are configured to expect.

There would be one breaking change as OpenAPI schema 3.1 no longer supports nullable (JSON Schema allows for arrays of types which is much more flexible), this would require changes to the extent.yaml definition. Although not a required change the migration docs also recommend changing example values to examples arrays.

[chris-little]

@m-burgoyne @tomkralidis @ghobona I support the move to OpenAPI V3.1 . Let's discuss at the next EDR API SWG. The changed schema for extent.yaml probably does not warrant a major release (V2!), and we can include in V1.2.

[chris-little]

EDR API SWG 122 2024-10-03 agreed to move to OpenAPI V3.1. @cmheazel agreed to investigate whther OGC API-common could support both versions cleanly for all APIs.

[cmheazel]

API Common section 6.6.2 states "This Standard includes a conformance class for OGC API definitions that follow the OpenAPI specification 3.0. Alternative API definition languages are also allowed. Conformance classes for additional API definition languages will be added as the OGC API landscape continues to evolve." So to support OpenAPI 3.1, we should add a conformance class for this standard. This should mirror an equivalent conformance class in API Common. Still to be resolved, how to distinguish between links to the version 3.0 and 3.1 documents when both are supplied. Note: one of the first elements in an OpenAPI document is the version number.

[m-burgoyne]

If a service supported multiple versions of OpenAPI one approach would be to use the format parameter f i.e. 3.1 would be: /api?f=application/openapi+yaml;version=3.1 /api?f=application/openapi+json;version=3.1

3.0 /api?f=application/openapi+yaml;version=3.0 /api?f=application/openapi+json;version=3.0

if a version is not specified in the request the default would be the newest version of OpenAPI defined in the conformance classes

[cmheazel]

@m-burgoyne good suggestion. I would make one modification --

API Common defines a "link" structure based on XLink. This structure includes a "type" property: "type: type: string description: A hint indicating what the media type of the result of dereferencing the link should be. example: application/geo+json"

So rather than use the "f" parameter, I would use the "type" property of the link to the OAS document.

[chris-little]

@cmheazel The debate about f or type to resolve whether OpenAPI is V3.0 or V3.1 ( or other variants) is useful, as the intent is that API EDR Part 1: Core V1.2 will support either or both versions.

[cmheazel]

@chris-little What we agree on is the use of MIME types (e.x. application/openapi+yaml;version=3.1). This will allow an EDR API to provide OAS documents using any version of the OAS standard.