search

opengeospatial / ogcapi-common

OGC API - Common provides those elements shared by most or all of the OGC API standards to ensure consistency across the family.
https://ogcapi.ogc.org/common
Other
45 stars 14 forks source link

Use and recommend OpenAPI 3.1 #208

Open joanma747 opened 3 years ago

joanma747 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

What about leaving it open?

bradh commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

cmheazel commented 3 years ago

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 commented 1 month ago

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

https://github.com/opengeospatial/ogcapi-environmental-data-retrieval/issues/580

https://github.com/opengeospatial/ogcapi-connected-systems/issues/48

https://github.com/opengeospatial/ogcapi-movingfeatures/issues/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 commented 1 month ago

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 commented 1 month ago

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 commented 2 weeks ago

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 commented 2 weeks ago

https://github.com/opengeospatial/ogcapi-features/pull/960#issuecomment-2428510369

@ghobona

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

ghobona commented 2 weeks ago

@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 commented 2 weeks ago

@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