Use and recommend OpenAPI 3.1

[joanma747]

The advantage of using JSON schema in OpenAPI document is an strong reason to recommend 3.1

Since it is currently approved, there is no reason not to do so. Unfortunately, it will take some time to have tools use it.

Reference: http://spec.openapis.org/oas/v3.1.0

[bradh]

I think the improvements are good. However the lack of tooling is contrary to the "easy to use goals" of OpenAPI. So maybe its a bit "too much, too soon". Depends on how soon common is coming out vs the tools and tutorials are mature.

[joanma747]

What about leaving it open?

[bradh]

I think leaving the ticket open for a future change is valid. [I assume you didn't mean leaving the version unspecified in OGC API Common.]

[cmheazel]

The current OpenAPI conformance class is for version 3.0. The trick will be how to add a conformance class for 3.1 in a simple and clean manner. Something which will scale for 3.2, 3.3, etc.
This may take a while so I suggest we defer this update to the next version of Common Core.

[cmheazel]

The OpenAPI Conformance Class is not mandatory. An implementation can use OpenAPI 3.1 as long as they advertise the fact.

[cmheazel]

March 1 2021 SWG:

1. OpenAPI version 3.1 will not be addressed in the OAB review of API-Common Part 1: Core version 1.0
2. This does not preclude APIs from implementing OpenAPI version 3.1.
3. The SWG will develop an approach to provide an OpenAPI Requirements Class that can be easily extended as new versions of OpenAPI are released.

[ghobona]

This topic has come up a number of times in other SWGs since 2022.

opengeospatial/ogcapi-environmental-data-retrieval#580

opengeospatial/ogcapi-connected-systems#48

opengeospatial/ogcapi-movingfeatures#57

The consensus slightly more than a year ago, regarding OpenAPI 3.1, was that tooling had not caught up with that of OpenAPI 3.0. However, some of the popular OpenAPI tools now support OpenAPI 3.1.

https://support.smartbear.com/swaggerhub/docs/en/openapi-3-1-support.html

https://redocly.com/docs/redoc

https://github.com/OpenAPITools/openapi-generator (beta support for 3.1)

So the question is: Are we ready to begin developing an extension of OGC API - Common that supports OpenAPI 3.1?

If so, then we would need collaboration across the various SWGs that have experimented with support for OpenAPI 3.1 before.

Please feel free to share your thoughts here. We will continue the discussion and aim to arrive at consensus during the OGC Member Meeting in Goyang, South Korea.

Cc: @alexrobin @cportele @chris-little @m-burgoyne @TaehoonK @rob-metalinkage @avillar

[cportele]

OGC API - Features - Part 1: Core version 1.1 will include a new requirements class for OAS 3.1 in addition to the existing requirements class for OAS 3.0. A pull request is being prepared.

Support for OAS 3.1 is in the Features API SWG charter since 2019, but we have not worked on this topic before this year waiting for tool support.

The SWG has not yet decided, if the API building blocks will be formally specified using OAS 3.0, OAS 3.1 or both. The only difference in the content is the treatment of null.

cc @pvretano

[chris-little]

We are considering adding OpenAPI V3.1 support to OGC API-EDR -Part 1: Core Version 1.2, but have not yet decided how to do it.

[ghobona]

A push request in the Features API SWG repo adding OpenAPI 3.1 examples is at https://github.com/opengeospatial/ogcapi-features/pull/960/commits

[Sam-Bolling]

opengeospatial/ogcapi-features#960 (comment)

@ghobona

With this comment in mind, are there any pitfalls identified for OGC API - Connected Systems going only on OAS 3.1?

[ghobona]

@Sam-Bolling OGC API - Connected Systems - Part 1 v1.0 currently only references OpenAPI 3.0 normatively.

The same goes for OGC API - Connected Systems - Part 2 v1.0.

So that ensures that the OGC API - Connected Systems standard is consistent with the OGC API - Features standard.

However, the example API definition document of OGC API - Connected Systems here implements OpenAPI 3.1. Rather than replace the OpenAPI 3.1 version of the example, we could simply upload an OpenAPI 3.0 version of the example to the same folder. Thereafter only the OpenAPI 3.0 version would be included in the release of OGC API - Connected Systems v1.0, whereas the OpenAPI 3.1 version would feed into cross-SWG discussions about a common approach to support OpenAPI 3.1.

@avillar has kindly created an OpenAPI 3.0 version of the OGC API - Connected Systems example API definition document. It is here. He will speak, remotely, about the process he went through during the Architecture DWG session on 4 November 2024 at the upcoming OGC Member Meeting.

[Sam-Bolling]

@ghobona do you think it is possible to consider a different option, where:

1. OGC API - Connected Systems releases with normative relationships to only OAS 3.1
2. The OAS 3.0 down down-compiling work is packaged as non-normative information in an appendix
3. The cross-SWG discussions determine a common approach to support OAS 3.1, and if needed OGC CSAPI update to that approach

If we consider the perspective of non-OGC adopters, I believe there is risk to releasing a new API at this time that is based on OAS 3.0 instead of OAS 3.1. Those non-OGC potential organizations are under constant pressure to adopt relatively competing solutions and standards. It is not uncommon for those advocating against adopting an OGC standard to compare it to an alternative that has moved on to a later version of an associated standard or technology. Conversely, it is an advantage OGC would miss out on to use that same logic to indicate the recently published OGC APIs are up-to-date with the most appropriate version of OAS at the time. If the concerns from 2021 about the misalignment of tooling support for OAS 3.1 and the principle of "ease of use and adoption" have been overcome; and the technical benefits of OAS 3.1 now outweigh the issues; I believe there is a great opportunity here for the OGC to release CSAPI based on OAS 3.1 in lieu of OAS 3.0

Of course, I could be missing something. There could be a technical challenge, issue, or blocker that would preclude CSAPI from making the upgrade from OAS 3.0 to OAS 3.1 at this time - I just do not know what that issue might be at this time.

Respectfully,

Sam