Resource specific collections

[Schpidi]

Do we want to allow resource specific collections? Common defines generic collections, sets of resources, which may even be of different type. Resource specific specifications might want to add collections with some sort of homogeneity criteria to support further concepts like map layers, mosaics, etc.

[bradh]

More generally, it might be useful to support an arbitrary grouping (perhaps by reference), as provided by OWS Context.

As a user, I don't really care about whether you have four mosaics, but I might care that there are related tiles and features.

[cportele]

In Features we have recently added an itemType member in the collection resource (default is 'feature' to be compatible with existing implementations) to allow for different resource types in the collections of an API:

https://github.com/opengeospatial/WFS_FES/blob/master/core/openapi/schemas/collection.yaml

Other values could be 'coverage', 'record', etc.

[jonathan-geoseer]

In Features we have recently added an itemType member in the collection resource (default is 'feature' to be compatible with existing implementations) to allow for different resource types in the collections of an API:

https://github.com/opengeospatial/WFS_FES/blob/master/core/openapi/schemas/collection.yaml

Other values could be 'coverage', 'record', etc.

I'm +1 on this. The ability to "Join" services together that are all actually the same thing is something that's difficult currently.

From a statistics perspective, across the ~200,000 OGC services in the GeoSeer index, about half of them have multiple service types on the same endpoint (i.e. both WMS and WFS at example.com/geoserver/). The other half only have a single service type on a given endpoint.

[bradh]

Why do you want to know what the itemType is? (Or why do you think a client might care?)

I think its more useful to know what the return format is. If its a mime type you can't handle, does it really matter whether its a feature or coverage?

[ghobona]

@Schpidi, @jonathan-geoseer, @cportele, @bradh,

This issue has now been moved to the OGC API - Common repository.

[joanma747]

I was in favor of the itemType concept but I'm not anymore.
My reasons are:
1.- a collection can be offered simultaneously as items, as maps or even as coverages. See: opengeospatial/ogcapi-coverages#25
2.- in /collections/collectionId there is a wya to include links. A collectionId that is available as items is supposed to advertise itself as a href with rel=items. The same can be done for coverages, maps, tiles etc. If the coverage is available as coverage and features, them there will be two links.

Could we withdraw the idea of itemType?

[joanma747]

In the effort to allow for a collection that can be anything (not just Features) we agreed on:

• itemType is only for specifying what type of "item" we are talking about if the collection is available as items (e.g. features, records...). It is NOT specifying what type of collection we are talking about: collections can have multiple "manifestations" in features, maps, tiles, coverages
• To know if a collection is available as items, maps, tiles... you have two alternatives:
  • Just try it and if you get a 404 it was not available :-)
  • Ask for the links returned by /collections/{collectionId} and look for the links. If there is a link to "items" it is "requestable" as items if there is link to maps it can be retreived as maps...

So if there is no link to items in /collections/{collectionId}, the collection is not retrievable as features.

I would like to include this text or something similar as a clarification in OWS common collections.

[aaime]

The Vector Tiles Pilot Phase 2 (VTP2) project found a need for "generic" collections that are not advertising much about their contents.

To make a specific point in case, say one wants to cascaded a common XYZ tile service offering mapbox vector tiles, wrapping it in a stand-alone Tile API (as in, one that does not offer feature or coverage resources on the side). For such case, all that is desired is to offer tiles, without exposing the internal layering structure as separate collections. That may go along with enough metadata to efficiently fetch them (for clients that do need a schema) , see here: opengeospatial/ogcapi-tiles#18

[jyutzler]

I am fundamentally opposed to generic collections that do not advertise much about their contents. When I GET/deserialize/unmarshal a document, I need to know what kind of document I am getting. There are two basic ways of doing this. The first is the itemType thing. I think you'll see when I describe the second approach that this approach is not all that useful.

The second approach is that there is a API contract for the type of document returned by a request. We kind of do this now because every oapi resource has the same basic pattern of links and content (which could have a multiplicity of 1 or n and the individual elements may have their own links). However, there is a ton of wiggle room in the links. This matters because the links are the function points for that document. What do we client developers have to write code for? The behaviors for the function points for the class representing a particular document.

This ambiguity is a major nuisance when it comes to collections. I never want to receive a generic collection. If I want a box of oranges, I don't want to order a box of fruit and throw out everything that isn't an orange. No, let's be specific regarding our resource types (including the links therein) and create specific methods to retrieve those specific resource types. This would work fine in every case, including the vector tiles case which is fairly complicated.

[jerstlouis]

The concept that I initially outlined in #17 is that of an abstract data resource. I believe there is great value in this, because it provides a mechanism to which modular blocks such as tiles, maps, etc. can connect to regardless of the type.

This means that the map and tiles conformance class specification only need to reference that abstract data resource specification, not specifically Features or Coverages, and it creates an exensibility point for additional modular specifications to attach to.

In turn that one abstract data resource can have multiple representations (e.g. Vector features, Raster coverages, 3D Mesh data). The goal was for that abstract resource to clearly link to one or more such representations, so it certainly should advertise that content through those links.

Assuming a abstract data resource at ../buildings, the description document could contain links to any of the following:

buildings/3dtiles -- 3D Tiles representation of those buildings
buildings/items -- Vector features
buildings/items/tiles -- Tiled vector features
buildings/items/map -- A map rendering these features
buildings/items/map/tiles -- A tiled map rendering these features
buildings/coverage -- A coverage representation of the buildings
buildings/coverage/tiles -- A tiled coverage representation of the buildings
buildings/coverage/map -- A map rendering the coverage representation of the buildings
buildings/coverage/map/tiles -- A tiled map rendering of the coverage representation of the buildings

buildings/map -- This could be a map rendering the default representation of the buildings
buildings/tiles -- This could be tiles of the default representation of the buildings
buildings/map/tiles -- This could be tiles of the map rendering the default representation of the buildings

Some property of the link (either a new one, the relation, and/or the media type) should clearly indicate what it is we are getting at that next link.

I think we have clarified that itemType was only relevant for Features or Records (itself originally based on features). Either the media type of the links, or an additional property for the links could identify which representation is being linked to.

[joanma747]

Move the "rel" that are note mention in core to collections or else. Examples of things that should be moved.

collection | The target IRI points to a resource which represents the collection resource for the context IRI. [IANA]
data | Refers to the root resource of a dataset in an API. [OGC]
items | Refers to a resource that is comprised of members of the collection represented by the link’s context. [OGC]
....
(https://github.com/opengeospatial/oapi_common/blob/master/core/clause_7_overview.adoc)

"rel" is extendable by default so no need to say anything in the mandatory text but a clarification could still be useful.
The JSON schema for links makes rel extendable.

[dblodgett-usgs]

I think the consensus that a collection is to be defined as:
"A geospatial data resource that may be available as one or more sub-resource distributions that conform to one or more OGC API standards."

And that we will have each OGC API specify a link relation for their representation of a collection, is enough to say this issue is resolved?

[cmheazel]

This issue was discussed in greater detail in issue #140. Issue #140 has been closed so this issue can be closed as well.