OpenAPI 3.1

[m-mohr]

OpenAPI 3.1 is in release candidate phase: https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0-rc0

While this is nothing for openEO API 1.0, there are quite a lot of good improvements that are highly relevant for us. Therefore, I may take OpenAPI 3.1 into consideration for an openEO API version 1.1 or so.

Benefits (from the ChangeLog):

• When using the Reference Object, summary and description fields can now be overridden.

  This will help with better describing things as at the moment and reduce the length of the OpenAPI document. Some of the descriptions are relatively general to allow reusability of several schemas and this could be improved.

• The Schema Object is now fully compliant with JSON Schema draft 2019-09

  The JSON Schema change is the most important benefit as it allows us to re-use the OpenAPI schemas and get rid of additional JSON Schemas like we have for the process graphs. It makes validation easier as more JSON Schema tooling is available. It also allows to make our OpenAPI file smaller as we can link to external JSON Schemas such as from STAC, GeoJSON etc.

Drawback will be that tooling will take some time to adopt, especially Spectral (for validation), OpenAPI Generator (for code generation) and ReDoc (for documentation) are important.

Other potentially interesting things or things we need to change:

• format (whether byte, binary, or base64) is no longer used to describe file payloads. As part of JSON Schema compliance, now contentEncoding and contentMediaType can be used for such specification.
• The nullable keyword has been removed from the Schema Object (null can be used as a type value).
• An OpenAPI Document now requires at least one of paths, components or webhooks to exist at the top level. While previous versions required paths, now a valid OpenAPI Document can describe only webhooks, or even only reusable components. Thus, an OpenAPI Document no longer necessarily describes an API.
• The Info Object has a new summary field.
• The License Object now has a new identifier field for SPDX licenses.
• Components Object now has a new entry pathItems, to allow for reusable Path Item Objects to be defined within a valid OpenAPI document.

Related issues:

• https://github.com/opengeospatial/ogcapi-features/issues/404
• https://github.com/radiantearth/stac-api-spec/issues/31

[aljacob]

well I guess we are certainly happy about the nullable improvement :p

[m-mohr]

Another release with changes: https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0-rc1

[m-mohr]

Final release: https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0

We need support at least in ReDoc and spectral here.