Difference between information provided by /collections and /collections/collectionId

[ghobona]

Currently there is an expectation that /collections/collectionId will return a more detailed response compared to /collections. However, it is unclear what exactly should be returned in /collections.

[cmheazel]

The August 10 update to the specification includes a short discussion on this topic. There is also a place holder for the list of recommended (recommendation 1) elements for the /collections coverage information. I hope this sprint will provide me what I need to populate it.

[joanma747]

Let me reiterate that /collections/collectionId is data-model-less. This means that at this point you do not know if your data is available as items (features) or coverages or other future "thing". Any new element on this response should be neutral. Adding the resolution of the data (in scaleDenominator?) or a more multidimensional bbox are possibilities but not much more than that.

Assuming that the attributes of a feature can be mapped to the values of a coverage (rangetype names), the idea of "queriables" (suggested in Testbed 15) could be used and reused by features or coverages or... So that could be another addition.

[jerstlouis]

@joanma747 while the collection of data itself conceptually is data-model-less, a particular API can still offer details in the .../collections/{collectionId} resource (extending Common - Part 2) which are specific to a supported API (view, e.g. Features and/or Coverages) way to access that data.

At least that was the conclusion of https://github.com/opengeospatial/ogc_api_coverages/issues/64 which included back and forth with Common, and resulted in e.g. extending extent to add extra dimensions (in addition to spatial and temporal), and links or properties in .../{collectionId} to specify the DomainSet and RangeType at that level.

This allows a simple /coverage just like you have a simple /items for Features. This also has me thinking again about /map being a description resource rather than a default map already, especially that the content of /map currently looks a lot like /styles :) (e.g. https://maps.ecere.com/ogcapi/collections/Daraa/styles vs. https://maps.ecere.com/ogcapi/collections/Daraa/map). (BTW in our server we give you back a default map already if you specifically ask for JPG or PNG... e.g. https://maps.ecere.com/ogcapi/collections/Daraa/map.png)

[joanma747]

Even if I sympathize with the idea of having model dependent information in .../collections/{collectionId} we avoided that in OGC API maps and tiles because we became convinced by others that it was not a good thing. I believe that the results is not so bad. I'll not start now populating the .../collections/{collectionId} with too many API specific info. There is nothing wrong with having this info directly in .../collections/{collectionId}/coverage

The alternative could be to allow everybody to include model dependent info in .../collections/{collectionId} and do that for performance reasons (e.g. reduce the number of http interactions.

So please, lets reach a consensus on that soon and let's try to be consistent in the different API standards.

[cmheazel]

One principle the JSON people have pounded into my head is that what is not recognized is ignored. So JSON, at least, is inherently extensible. However, "do your own thing" is not a good approach for a standard. So let's work out an approach for extending the collection information and then take that back to Common as a recommended mod.

[jerstlouis]

@joanma747

The alternative could be to allow everybody to include model dependent info in .../collections/{collectionId} and do that for performance reasons (e.g. reduce the number of http interactions.

That has my vote. Agreed it should be consistent.

There is nothing wrong with having this info directly in .../collections/{collectionId}/coverage

What this allowed is for /coverage to directly be your GeoTIFF or netCDF files where you can also do your subsetting etc., rather than being a metadata doument like /map right now.

Consequently this matches very nicely to Features where /items is directly your GeoJSON feature collection.

The domainset and rangetype might be part of the coverage, but having this info consistently always available in CIS JSON ensures that clients will always have a clear standard CIS-based description of the range set and domainset in a consistent manner, even if the coverage as a whole is only available in e.g. GeoTIFF.

As for /map, right now it's mainly a list of styles which is eerily similar to /styles, so i am wondering if reusing styles for listing available maps of multiple styles (to use for /map/{styleId} and /map/{styleId}/tiles), and by just adding one or two things to the .../{collectionId} resource we might not be able to have a default map at /map, elegantly mirroring Features & Coverages.

[Schpidi]

I agree with @jerstlouis, if we want /coverage to return the coverage itself e.g. as GeoTIFF than we need a higher path to provide the information needed to generate proper parameter values for the /coverage path, i.e. the range type and domain set.

[Schpidi]

20210303 Coverages SWG call: @cmheazel agreed to work on this as part of the ongoing effort to harmonize Common part 2 and Coverages

[jerstlouis]

SWG 2022-01-12:

Suggesting that we make progress on this regardless of the status of Common.

Common - Part 2 defines what should be present at /collections and /collections/{collectionId}, which includes the extent at both level.

In Coverages, we also require the use of the Uniform Additional Extent (for dimensions other than spatial and temporal) -- This should also be avialble at both level.

The links to the Coverage, RangeType and DomainSet could also be required at both level. However if the link is a JSONPointer to an embedded definition of the RangeType and/or DomainSet, those should not be at the /collections level but only at /collections/{collectionId}

[chris-little]

@jerstlouis @cmheazel I strongly prefer that Coverages API requirements are not pushed up to Common Part 2, unless there is a widespread requirement from the other APIs. Keep It (Common Part 2) Simple.

[jerstlouis]

@chris-little I fully agree with that, I was not suggesting otherwise. However, more commonality between specifications of the OGC API family = a lot more simplicity and interoperability for developers and users.

The requirement for links to the Coverage, RangeType and DomainSet at both levels and the requirement for Extent-Uniform Additional Dimensions (defined as a Common requirement module) are additional Coverages requirements.

This specific issue is about what extra information should be returned when requesting a single collection at /collections/{collectoinId} vs. when requesting the list of all collections /collections, here specifically for Coverages, but guidance from Common in this regard would be useful.

e.g. in EDR, are the parameter names, full temporal extent details, and query types described at both /collections and /collections/{collectionId}, or are these only included at /collections/{collectionId} ?

Adopting the Extent-Uniform Additional Dimensions in other specifications where it makes sense would also be a good thing -- I think it would work with EDR except for the issue with the basic Common-Part 2 extents.

[cmheazel]

In API-Coverages the /collections operation is described in section 7.1 and the /collections/{collectionId} operation is described in section 7.2. Both sections refer to section 7.3 for a description of the collection resource. Section 7.3 documents the Coverage specific extensions to the collection resource from API-Common. Currently the Uniform Additional Dimensions extent is the only extension identified.

Note that the definition of the collection resource is the same for both the /collections and /collections/{collectionid} operations. The standard leaves it up to the implementer to select the best set of metadata to include with each operation. The API-Coverages standard should provide a rich set of options, but minimize required content.

[jerstlouis]

@cmheazel

• What Coverages adds to /collections/{collectionId} (in addition to the UAD extent -- which is actually more of a restriction, than an extension) is the requirement to include 3 links to:

  • The /coverage resource
  • A domainset resource (either to a JSON pointer in the same document, or to the recommended path /coverage/domainset)
  • A rangetype resource (either to a JSON pointer in the same document, or to the recommended path /coverage/rangetype)

• This issue is mostly about whether those 3 links are also required as part of the object included in the array in /collections or not.

  • The advantage of saying yes is that it avoids an additional server roundtrip to fetch the /collections/{collectionId} to retrieve those links.
  • The advantage of saying no is to lighten the content of /collections, which may already contain several collections. The domainset in particular could be is huge, e.g., the way CIS is structured, a billion points point clouds would require the billion coordinates listed in the domainset -- which is quite different than a GeneralGridCoverage where only its bounds are specified.
  • The compromise might be what I had suggested: require a liink, but recommend to link to a JSON pointer to /collections/{collectionId} (or not use JSON pointer and link to /coverage/domainset and /coverage/rangetype), not to somewhere in the full /collections.

[cmheazel]

A new requirement has been introduced making these three links mandatory.

[chris-little]

@cmheazel @jerstlouis As I said before, as long as this is a requirement on Coverages and not on Common.

[jerstlouis]

SWG 2022-06-08

@chris-little The requirement is specific to Coverages. The requirements have been clarified that any collection resource when conforming to GeoData coverage is required to contain links to all 3 resrouces: the coverage, domainset and rangetype. Applied in 604f28b1756d75f7999aa95389ebb006b00bd719