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
48 stars 14 forks source link

Requirement to use 'data' as a relation type in the Landing Page is missing #294

Open ghobona opened 3 years ago

ghobona commented 3 years ago

The requirement to use 'data' as a relation type in the Landing Page, for identifying the path to the collections resource, appears to be missing.

I checked:

I suspect that it got left out during the separation of OGC API - Common

ghobona commented 3 years ago

Cc: @cmheazel @jerstlouis

jerstlouis commented 3 years ago

@ghobona @cmheazel I believe the requirement should be in OGC API - Common - Part 2:

The OGC API landing page response links SHALL include a link to the set of available collections (at /collections) using the link relation type http://www.opengis.net/def/rel/ogc/1.0/data.

ghobona commented 3 years ago

@cmheazel This issue is partially addressed by the first paragraph of Clause 8.1 of OGC API - Common - Part 2, so it is a minor issue. However, I think that after the Public Comment stage, the text suggested by @jerstlouis above (https://github.com/opengeospatial/ogcapi-common/issues/294#issuecomment-885481369) should added to one of the existing requirements (e.g. to become Requirement 1C).

cmheazel commented 3 years ago

@ghobona Sorry we can't do that. Such a requirement can only be validated if both the landing page and collections conformance classes are implemented. And it has been made quite clear that we cannot make that assumption. Notice that Part 2 requirement /req/collections/rc-md-op does not specify where in the API the /collections path appears. All we know is where we can go from this base. We have no knowledge of, and can make no assumptions about, what lies below the /collections resource.

jerstlouis commented 3 years ago

@cmheazel The essence of my proposal (or @ghobona 's too, I think) is to define the link relation type to link from anywhere (e.g. an API landing page) to a /collections (regardless of where that happens to be).

Perhaps a conditional requirement could work?

If the API conforms to OGC API - Common Part 1: Core - Landing Page conformance class and offers a dataset-wide list of collections, the Landing Page response's links SHALL include include a link to the set of available collections (at /collections) using the link relation type http://www.opengis.net/def/rel/ogc/1.0/data.

ghobona commented 3 years ago

@cmheazel Ok, that's fine. I suspect that standards that implement OGC API - Common will introduce the requirement themselves. We just need to ensure that the requirement is specified consistently by the standards. So perhaps a Conditional Requirement in OGC API - Common (as @jerstlouis suggested) might be more appropriate than a Requirement.

cmheazel commented 2 years ago

Added part B (below) to Requirement 2 (GET /collections). A - The API SHALL support the HTTP GET operation at the path /collections. B - The API SHALL support the HTTP GET operation on all links to a Collections Resource that have the relation type http://www.opengis.net/def/rel/ogc/1.0/data.

cmheazel commented 2 years ago

See also issues #132 and #273

jerstlouis commented 1 year ago

@cmheazel

The new requirement B is very confusing to me:

B - The API SHALL support the HTTP GET operation on all links to a Collections Resource that have the relation type http://www.opengis.net/def/rel/ogc/1.0/data.

EDITED: (I had misread). The confusion is from talking about GET operations on links rather than on resources.

While Part 2 cannot add requirements to Part 1, what I believe it can do is specify conditional requirements that are then applied to any relevant Standard (OGC or otherwise) on how to link to the resource.

e.g., see OGC API - Tiles Section 10.3.1 (Requirement 11 A):

If the API has a mechanism for exposing root resources (e.g., a landing page), the API SHALL advertise at least one URI to retrieve a tilesets list provided by this service with a link having a rel value: http://www.opengis.net/def/rel/ogc/1.0/tilesets-vector, http://www.opengis.net/def/rel/ogc/1.0/tilesets-map or http://www.opengis.net/def/rel/ogc/1.0/tilesets-coverage.

So something like:

If the API has a mechanism for exposing root resources (e.g., a landing page), the API SHALL advertise at least one URI to retrieve the list of collections provided by this service with a link having a rel value: http://www.opengis.net/def/rel/ogc/1.0/data.

The requirement can then easily be validated if a CITE test is testing Common - Part 2 as well as another standard (e.g., Part 1).

See also https://github.com/metanorma/metanorma-ogc/issues/439 for related discussions about conditional requirements in the context of the ModSpec and metanorma.

(this issue is mostly a duplicate of #273 )

NOTE: Commenting on this in the context of testing a new not yet conforming OGC API implementation (something I feel like I'm doing for the hundredth time ;)) where our client does not get past the landing page. A Common Part 1 and 2 Standard and an associated simple Test Suite would really be super useful to allow OGC API implementation developers to easily perform basic validation early on that guarantee clients can get from the landing page to collection for all OGC API data access APIs. Technically, they could probably run any of the OGC API data access test suites like Features or EDR or the early Tiles one, but it is counter-intuitive if not implementing those APIs.