Discoverability of OGC API - Tiles resources

[m-mohr]

This issue is somewhat related to #40.

I'm trying allows users to add links to various OGC API - Tiles endpoints by defining link structures via the STAC Web Map Links extension: https://github.com/stac-extensions/web-map-links

The STAC Web Map Links extension allows to add links to the STAC links section with pre-defined relation types so that clients can automatically render WMTS, OGC API - Tiles, and other resources directly and automatically on a map. For this there need to be distinct rel types so that the right code can be executed (e.g. the right layer class can be initiated in OpenLayers).

For example, for WMTS we simply defined the rel type wmts which links to the WMTS base url. Or the rel type xyz links to the templated URI of the XYZ.

The same I'd like to allow for OGC API - Tiles. Unfortunately, there are so many different access paths. You could for example link to the landing page, a specific collection, a tileset or a templated URI directly.

So there are basically multiple questions:

1. If I write a Tiles client for a mapping library such as Leaflet so that I can show a layer on the map, what are all the potential endpoints users could provide? OpenLayers says something like "URL to the OGC Map Tileset endpoint.", but that seems rather unclear to me. This should be guided by OGC API - Tiles so that the implementations do not diverge too much.
2. Can OGC API - Tiles pre-defined the relation types for this linking mechanism described above or do we need to "invent" our own relation types in STAC?

[m-mohr]

For 1, I got the following response from @jerstlouis (I think). While it explains the situation, there should still be more guidance somewhere in best practice or so, I think.

@jerstlouis wrote:

---

Excellent question... There are basically multiple places that a user could point a Tiles client to. The three main ones are:

1. An OGC API landing page (Common - Part 1) e.g., https://maps.gnosis.earth/ogcapi
2. An OGC API Collection (Common - Part 2) e.g., https://maps.gnosis.earth/ogcapi/collections/blueMarble
3. Metadata for a specific Tileset (OGC API - Tiles and 2DTS&TSMD) e.g., https://maps.gnosis.earth/ogcapi/collections/blueMarble/map/tiles/WorldCRS84Quad -- this is what OL means by the "OGC Map Tileset endpoint"

You could also decide to support accepting/recognizing the intermediate lists:
4) List of collections e.g., https://maps.gnosis.earth/ogcapi/collections
5) List of tilesets e.g., https://maps.gnosis.earth/ogcapi/collections/blueMarble/map/tiles

As far as I know the GDAL OGC API driver (https://gdal.org/drivers/raster/ogcapi.html) supports 1) and 2) (with options to select or prefer a particular TileMatrixSet), whereas OpenLayers expects 3) ( see e.g., https://openlayers.org/en/latest/examples/ogc-vector-tiles.html ).

In terms of what rel type to look for:

1. Landing Page -> 4) List of collections uses [ogc-rel:data]
2. List of collections -> 2) Collection description uses self (inside a collections array)
3. Collection description or 1) Landing Page (dataset tiles)-> 5) list of tilesets uses [ogc-rel:tilesets-map], [ogc-rel:tilesets-vector] or [ogc-rel:tilesets-coverage]
4. List of tilesets -> 3) individual tileset metadata uses self (inside a tilesets array)
5. individual tileset metadata to individual tiles uses item with a templated = true link in links property, using {tileMatrix}, {tileRow} and {tileCol} variables.

The diagram in section 6.5 ( https://docs.ogc.org/is/20-057/20-057.html#toc25 ) is useful to find your way.

There is yet another origin that can lead to lists of tilesets: the /styles resources (combining with OGC API - Styles), which will also use [ogc-rel:tilesets-*].

[m-mohr]

Examples for links:

Link to a Tiles landing page (not sure whether that's any useful, maybe better use one of the links below?):

    {
      "href": "https://tiles.example.com",
      "rel": "ogcapi-tiles", # relation type invented by me, is there a better one?
      "type": "application/json",,
      "ogcapi-tiles:collection": "abc"
      "ogcapi-tiles:tiling-scheme": "WebMercatorQuad"
    }

Link to a Collection:

    {
      "href": "https://tiles.example.com/collections/abc",
      "rel": "ogcapi-tiles-collection", # relation type invented by me, is there a better one? "http:/www.opengis.net/def/rel/ogc/1.0/geodata" doesn't work due to the ambiguity (could also be a link to a non-Tiles resource such as a Feature or Record)
      "type": "application/json",
      "ogcapi-tiles:tiling-scheme": "WebMercatorQuad"
    }

Link to a Tileset:

    {
      "href": "https://tiles.example.com/collections/abc/tiles/WebMercatorQuad",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/tileset-map", # currently undefined, but see #148 
      "type": "application/json"
    }

Link to a templated URI:

    {
      "href": "https://tiles.example.com/collections/abc/tiles/WebMercatorQuad/{tileMatrix}/{tileRow}/{tileCol}",
      "rel": "ogcapi-tiles-uri", # relation type invented by me, is there a better one? "item" doesn't work due to the ambiguity (could also be a link to a STAC Item)
      "type": "image/png"
    }

... and what else?

[jerstlouis]

My suggestion would be:

    {
      "href": "https://tiles.example.com/collections/abc/tiles",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/tilesets-map",
      "type": "application/json"
    }

This would allow clients to pick a specific tile matrix set.
The list of tilesets and individual tilesets can also link back to the collection and landing page.
Landing page, collections and tilesets list can support multiple 2D Tile Matrix Sets, so I think the ogcapi-tiles:tiling-scheme would be more appropriate for the tiles template and the individual tileset than where they are currently used above.
If defining a templated URL, we've so far used "templated": true inside the links.

[christophenoel]

With a s:
http://www.opengis.net/def/rel/ogc/1.0/tilesets-map

[jerstlouis]

@christophenoel Thanks for the correction, yes, that is the correct link relation to link to a list of tilesets, which I believe what my comment was about.