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

What capabilities should be added or kept in OpenAPI 4.x in order to meet the needs of OGC API Standards? #339

Closed ghobona closed 1 week ago

ghobona commented 5 months ago

OpenAPI 4.0 is planned to be released in 2024.

An April 12, 2024 blog post summarising the current progress is at https://apisyouwonthate.com/blog/openapi-v4-project-moonwalk/

Some of the progress can be tracked on GitHub.

The question for OGC API developers is what capabilities should be highlighted as "must-keep" or "must-add" for OpenAPI 4.0?

This GitHub Issue will be closed on May 15, 2024.

jerstlouis commented 4 months ago

@ghobona In my opinion operation IDs are a critical things to keep, but my question if they are proposing to drop that, is whether there is anything equivalent being introduced in 4.0 that replaces operation IDs?

The reason why we have defined an operation ID req. class in Maps, Tiles and DGGS is to have a mechanism to map the end-points in an API description document with requirements in the OGC standards.

Without this, nothing connects the two, especially if the requirement classes do not mandate a specific path (as is the case with tiles in particular).

How do you now that https://example.com/foo/bar/bob/{z}/{y}/{x} implements OGC API - Tiles "Core" and that these are tiles that follow 2D Tile Matrix Set?

Operation IDs (suffixes) allow to connect a path in the API definition to clauses in OGC standards. With the suffixes concept, you can have multiple paths that conform to the same clauses (e.g., for different collections).

So if 4.0 does not propose something equivalent, then yes I believe we should advocate for operationIDs being "must-keep".

Regarding "must-add", it would really be great if we could have the values of path parameters be able to depend on other path parameters. For example, the valid {styleId} within a particular {collectionId}.

I mentioned this and a few other things in https://github.com/opengeospatial/ogcapi-common/issues/302 .

According to https://github.com/OAI/OpenAPI-Specification/issues/2453#issuecomment-1913414315 , $dynamicRef in OpenAPI 3.1 might already be able to provide that capability, but we did not investigate whether it actually solves the issue. Would be great if it does!

I'm also a bit concerned that we are closing this issue with no one else having replied to it yet! :)

Maybe it slipped through everyone's busy radar.

ghobona commented 4 months ago

Thanks @jerstlouis .

I'll keep the issue open until 30 June 2024 and remind the SWGs to respond.

ghobona commented 2 months ago

This issue will be closed at 17:00 EDT on 30 June 2024.