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

[ghobona]

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:

• OGC API - Common - Part 1
• OGC API - Common - Part 2
• OGC API - Coverages - Part 1

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

[ghobona]

Cc: @cmheazel @jerstlouis

[jerstlouis]

@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]

@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 (#294 (comment)) should added to one of the existing requirements (e.g. to become Requirement 1C).

[cmheazel]

@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]

@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]

@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]

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]

See also issues #132 and #273

[jerstlouis]

@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 metanorma/metanorma-ogc#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.