Support for OpenAPI 3.1

[cportele]

Support for OpenAPI 3.1 is already in our Charter. The work on that version has seen some delays in the OpenAPI initiative, but 3.1.0-rc0 has now been released. Since the release is now getting closer, this issue is intended to track the progress and serve as a starting point for the work on the OpenAPI 3.1 requirements class.

The key improvements for us in that version seem to be:

• the ability to specify OpenAPI documents without path items (what Swagger currently calls domains and which we have been using for the building blocks on SwaggerHub)
• support for JSON Schema draft 2019-09 instead of the OpenAPI 3.0 Schema object
• support for mutual TLS
• better support for webhooks

As an aside, they are also getting rid of the use of "RESTful" 😉. We use Web API, they move to HTTP API.

[akuckartz]

they are also getting rid of the use of "RESTful"

Well, they never seemed to conform to all REST criteria.

[m-mohr]

Just curious: Why is this tagged with "support in extension"?

[cportele]

@m-mohr - Because the current plan is to add this in a new part (part 5). The OpenAPI 3.0 conformance class will continue to exist in part 1. Maybe we will also decide to add OpenAPI 3.1 as an additional conformance class in part 1, but this is not what the current charter says.

[m-mohr]

Wouldn't that lead to quite some redundant work as two separate OpenAPI definitions need to be maintained in the specs? I'm just wondering, because it also seems that if you want to do OpenAPI 3.1 in "implementing"/extending APIs such as STAC or openEO, you'd also have to maintain 3.0 and 3.1 in all of them?

[cportele]

We will have to keep the OpenAPI 3.0 conformance class "forever" (or at least as long as it is used in practice, maybe it can be deprecated at some point, but that will not be anytime soon). Support for multiple API definitions is part of the design, like support for multiple feature encodings.

And APIs don't have to support both, they may also decide to support only 3.0 or 3.1, typically depending on knowledge about clients that will process the API definition. Just like we worked 2-3 years ago initially also with Swagger / OpenAPI 2.0 since tooling often didn't support OpenAPI 3.0 yet, but dropped that once tooling support was there.

[m-mohr]

Yes, understood, but I was more referring to the maintenance of the OpenAPI files in this repo and the STAC repo etc. Not so much about the actual API implementations linking to the files via service-doc/desc. That for sure needs to stay as it is for compliance. So you'll manage two OpenAPI definitions for each OpenAPI version separately or is there something like a 3.1 to 3.0 converter (or so) planned?

[cportele]

It is something for discussion, but I think we will end up with providing the building blocks in both for 3.0 and 3.1.

Strictly this would not be necessary just for the standard, since we (currently) use OpenAPI 3.0 to formally specify the requirements. But for reuse in implementations we should provide all building blocks in both versions, in particular as 3.1 is not backwards compatible with 3.0 (OAS no longer uses semantic versioning).

[cportele]

Finally, OpenAPI 3.1.0 has been released: https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0