search

opengeospatial / ogcapi-tiles

OGC API - Tiles draft specification
https://ogcapi.ogc.org/tiles
Other
37 stars 18 forks source link

tilesets resource only contains links to tileset resources. May we remove the thing completely? #43

Closed joanma747 closed 3 years ago

joanma747 commented 4 years ago

We introduced the following flow: geospatial data resource --> tilesets --> tileset --> tiles

It was unclear if tilesets will provide all the necessary information to bypass tileset completely (by reproducing all the info in the tileset documents. If we do, I have a problem: the tilesets will enumerate tileset links as well as tile templates. Both have the "item" rel because both are providing pieces of the tilesets. Then I cannot separate them easily.

For the moment I give up and tilesets will only contain links to tileset.

But then, I believe we could include the links to tileset directly on the geospatial data resource (that is forced to have one link to tilesets anyway). Then the need for tilesets is removed.

So my final recommendation is to remove tilesets and have multiple links in the geospatial data resource

chris-little commented 4 years ago

This seems quite similar to the issue we have had in API-EDR - different instances of the same collection within collectionS. We decided to allow both patterns:

  1. Collections/{CollectionId}/Query
  2. Collections/{CollectionId}/Instances/{InstanceId}/Query

Instances could have identical spatio-temporal extents, or even differing, providing they all met the selection by extent at the Collections level.

joanma747 commented 4 years ago

WE agree on 2020/07/16 that "geospatial data resource" will have a list of "tileset" (and optionaly an extra link to a "tileset list" that we will say is just a list o links but we will not specify as requirements) tileset only includes one TMS and the template to tiles.

This will save as a conformance class.

jerstlouis commented 4 years ago

@joanma747 @cportele @pomakis Have we decided what that list of tilesets looks like? I think we had not thought this through to the end.

Is that directly in links, or is that a new property tilesets directly in the collection resource, which could e.g. include the TMS identifier? It would be painful if a server supports 100 TMSes to have to query all of them to try to find the one TMS that you support as a client.

The latter makes sense. You would omit the tileMatrixSetLimits though at that level. A related question remains about tileMatrixSetURI vs. tileMatrixSet, which by the way I believe got mistakenly moved to the 2D-TMS repo:

https://github.com/opengeospatial/2D-Tile-Matrix-Set/issues/3 -- This is a Tiles API issue, not 2D-TMS.

The tileMatrixSetURI vs. identifier is a mess right now. It's really not clear how it works. I would suggest only have "tileMatrixSet", and the last part after a / (stripped of any ?query parameters) is an identifier, which must match the TMS name in the 2D-TMS standard if there is one defined in there (this would allow to use a local link as opposed to always linking to the authoritative OGC one). If we keep separate identifier and tileMatrixSet, then we really are not using tileMatrixSet as a URI, but as a link (URI stands for Identifier! Having both "identifier" and "URI" is super confusing).

https://github.com/opengeospatial/2D-Tile-Matrix-Set/issues/2 -- Also a Tiles API issue, not 2D-TMS.

So I would suggest the following to hit many birds with one stone here...

In the {datasetAPI}/collections/{collectionId} resource (and optionally also at {datasetAPI}/collections/{collectionId}/tiles):

   ...
   "tilesets" : [
      // Your coverage elevation values tiles...
      {
         "dataType" : "values", // (coverage data values)
         "tileMatrixSet" : "http://maps.ecere.com/ogcapi/tileMatrixSets/WebMercatorQuad",
         "links" : [
            {
               "rel" : "ogc:tiles:tileset",
               "type" : "application/json",
               "href" : "http://maps.ecere.com/ogcapi/datasets/vtp:daraa/collections/dted/coverage/tiles/WebMercatorQuad"
            },
            {
               "rel" : "ogc:tiles:tileset",
               "type" : "application/json+tilejson",
               "href" : "http://maps.ecere.com/ogcapi/datasets/vtp:daraa/collections/dted/coverage/tiles/WebMercatorQuad?f=tilejson"
            }
         ]
      },
      // Your elevation contours vector tiles...
      {
         "dataType" : "vector",
         "tileMatrixSet" : "http://maps.ecere.com/ogcapi/tileMatrixSets/WebMercatorQuad",
         "links" : [
            {
               "rel" : "ogc:tiles:tileset",
               "type" : "application/json",
               "href" : "http://maps.ecere.com/ogcapi/datasets/vtp:daraa/collections/dted/tiles/WebMercatorQuad"
            },
            {
               "rel" : "ogc:tiles:tileset",
               "type" : "application/json+tilejson",
               "href" : "http://maps.ecere.com/ogcapi/datasets/vtp:daraa/collections/dted/tiles/WebMercatorQuad?f=tilejson"
            }
         ]
      },
      // Your rendered map tiles...
      {
         "dataType" : "image",
         "tileMatrixSet" : "http://maps.ecere.com/ogcapi/tileMatrixSets/WebMercatorQuad",
         "style" : "http://maps.ecere.com/ogcapi/datasets/vtp:daraa/styles/night",
         "links" : [
            {
               "rel" : "ogc:tiles:tileset",
               "type" : "application/json",
               "href" : "http://maps.ecere.com/ogcapi/datasets/vtp:daraa/collections/dted/map/night/tiles/WebMercatorQuad"
            },
            {
               "rel" : "ogc:tiles:tileset",
               "type" : "application/json+tilejson",
               "href" : "http://maps.ecere.com/ogcapi/datasets/vtp:daraa/collections/dted/map/night/tiles/WebMercatorQuad?f=tilejson"
            }
         ]
      }
   ]
   ...

And an OGC API - Tiles default JSON encoding for one of those 3 tilesets would be:

{
   "links" : [
      {
         "rel" : "self",
         "type" : "application/json",
         "title" : "Vector contours tileset for the Daraa elevation layer",
         "href" : "http://maps.ecere.com/ogcapi/datasets/vtp:daraa/collections/dted/tiles/WebMercatorQuad"
      },
      {
         "rel" : "ogc:tiles:tile",
         "type" : "application/vnd.mapbox-vector-tile",
         "title" : "Vector contour tiles for the Daraa elevation layer (as Mapbox Vector Tiles)",
         "href" : "http://maps.ecere.com/ogcapi/datasets/vtp:daraa/collections/dted/tiles/WebMercatorQuad/{tileMatrix}/{tileRow}/{tileCol}?f=mvt",
         "templated" : true
      }
   ],
   "layers" : [
      {
         "name" : "contours",
         "vectorType" : "lines",
         "fields" : [
            {
               "name" : "elevation",
               "type" : "number"
            }
         ]
      }
   ],
   "tileMatrixSet" : "http://maps.ecere.com/ogcapi/tileMatrixSets/WebMercatorQuad",
   "tileMatrixSetLimits" : [
      { "tileMatrix" : "0", "minTileRow" : 0, "maxTileRow" : 0, "minTileCol" : 0, "maxTileCol" : 0 },
      { "tileMatrix" : "1", "minTileRow" : 0, "maxTileRow" : 0, "minTileCol" : 1, "maxTileCol" : 1 },
      { "tileMatrix" : "2", "minTileRow" : 1, "maxTileRow" : 1, "minTileCol" : 2, "maxTileCol" : 2 },
      { "tileMatrix" : "3", "minTileRow" : 3, "maxTileRow" : 3, "minTileCol" : 4, "maxTileCol" : 4 },
      { "tileMatrix" : "4", "minTileRow" : 6, "maxTileRow" : 6, "minTileCol" : 9, "maxTileCol" : 9 },
      { "tileMatrix" : "5", "minTileRow" : 12, "maxTileRow" : 12, "minTileCol" : 19, "maxTileCol" : 19 },
      { "tileMatrix" : "6", "minTileRow" : 25, "maxTileRow" : 25, "minTileCol" : 38, "maxTileCol" : 38 },
      { "tileMatrix" : "7", "minTileRow" : 51, "maxTileRow" : 51, "minTileCol" : 76, "maxTileCol" : 76 },
      { "tileMatrix" : "8", "minTileRow" : 103, "maxTileRow" : 103, "minTileCol" : 153, "maxTileCol" : 153 },
      { "tileMatrix" : "9", "minTileRow" : 206, "maxTileRow" : 207, "minTileCol" : 307, "maxTileCol" : 307 },
      { "tileMatrix" : "10", "minTileRow" : 413, "maxTileRow" : 414, "minTileCol" : 614, "maxTileCol" : 615 },
      { "tileMatrix" : "11", "minTileRow" : 826, "maxTileRow" : 828, "minTileCol" : 1228, "maxTileCol" : 1231 },
      { "tileMatrix" : "12", "minTileRow" : 1652, "maxTileRow" : 1657, "minTileCol" : 2456, "maxTileCol" : 2463 },
      { "tileMatrix" : "13", "minTileRow" : 3304, "maxTileRow" : 3314, "minTileCol" : 4912, "maxTileCol" : 4927 },
      { "tileMatrix" : "14", "minTileRow" : 6608, "maxTileRow" : 6628, "minTileCol" : 9825, "maxTileCol" : 9855 },
      { "tileMatrix" : "15", "minTileRow" : 13216, "maxTileRow" : 13257, "minTileCol" : 19651, "maxTileCol" : 19711 },
      { "tileMatrix" : "16", "minTileRow" : 26433, "maxTileRow" : 26514, "minTileCol" : 39303, "maxTileCol" : 39423 },
      { "tileMatrix" : "17", "minTileRow" : 52866, "maxTileRow" : 53028, "minTileCol" : 78606, "maxTileCol" : 78847 }
   ]
}

And you also have the alternative TileJSON encoding for that tileset description.

cportele commented 4 years ago

@jerstlouis - That looks good to me.

Except for the link relation type (my proposal http://www.opengis.net/def/rel/ogc/1.0/tileset) and the TileJSON media type that does not exist. And we should discuss, if it makes sense to reuse the layer information from TileJSON or to harmonize the fields-information with the queryables-information.

jerstlouis commented 4 years ago

@cportele I don't really care what the relation types are named, but I do strongly prefer that each OGC API resource has a clearly defined associated relation type, rather than a vague generic name which may be used in very different contexts. e.g. see the relation types I proposed for OGC API - Coverages (including many Common Core & GeoData ones): https://github.com/jerstlouis/ogc_api_coverages/blob/master/standard/clause_6_overview.adoc .

I liked the "ogc:{spec}:{resourceName}" scheme, but Gobe did mention it had been decided to use HTTP URIs for them. However when I looked at http://www.opengis.net/def/rel/ I did not see anything with full URLs? I am fine with that proposed tileset one though if that is what was agreed upon.

As for the TileJSON media type, can we define one? If we can't define new media types as needed, then we need to use an additional member in the link to distinguish different kinds of JSON (e.g. like "schema" in OGC API - Processes format).

A note about the TileJSON fields: what we defined in VTP2 changed the actual TileJSON 3.0 definition. Also I always thought it was missing an optional description.

Agreed about the layers / fields, that was just an aside reminder that we had not yet defined this but that it is important.

jerstlouis commented 4 years ago

Replying to @pomakis comments about /tiles from https://github.com/opengeospatial/2D-Tile-Matrix-Set/issues/3#issuecomment-663682816

Removing /tiles was the result of a SWG decision on July 16th. To clarify, it could potentially be specified (it provides a list of tilesets), but not required.

I think @joanma747 's main reason to suggest removing it was it allowed to do away with one less conformance class. Looking at the title of this issue, it actually contains more than only links, it should also specify the type of data the tile contains and a tileMatrixSet property (and/or other related TMS properties).

If it seems like it really takes up too much to list the available tile sets, it may be a good reason to bring it back. And in fact, it might make sense to have it in its own conformance class, TilesetsList, which both GeoData-tilesets and Dataset-tilesets could re-use and share, defining "How do you list tilesets?", and "What should be in each element of a tilesets list?". TileMatrixSetLimits is one thing that should not be there.

But If we do bring it back, then I suggest that the /tiles end-point would list all tilesets (whether coverage data tiles, vector data tiles and/or map images tiles -- and those need to be clearly identified, hence the dataType property), and the {collectionId} resource could simply have a single link to the Tiles API distribution. And like the draft listing of tilesets above, /tiles should link to tilesets, indicating their TMS and linking to Tilesets resources (not directly to tiles).

The resource at the URL "https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/collections/Daraa_DTED/map/Night/tiles?f=json" is all a client application needs in order to know how to generate a navigatable map of the Daraa_DTED collection in the Night style.

With the new conformance classes, the Tileset (with a specific TMS selected) becomes more of a first class object, recognizing the importance of the Tileset concept in the community. So whether tilesets are directly linked from the {collectionId} resource, or that only contains a link to /tiles, you could always:

joanma747 commented 4 years ago

I have applied the change.

A tileset SHALL be linked directly from the dataset of a collection with the path .../tiles/{timematrixsetid} (rel tiles)

Optionally a tilesets resource can be liked too with the path .../tiles (rel tilesets)

I'll close the issue if there is no objection

jerstlouis commented 4 years ago

@joanma747 I do object to having the tilesets simply linked from the links property, because it does not provide the necessary information. In that example:

  "id": "buildings",
  "title": "Buildings in the city of Bonn",
  "description": "This collection contains buildings",
  "attribution": "OpenStreetMap",
  "extent": {
    ...
  }
  "links": [
    ...
    {
      "href": "http://data.example.com/collections/buildings/tiles/WebMercatorQuad",
      "rel": "tiles",
      "type": "application/json",
    }
  ]
}

There's no way to know:

You don't want the client to have to fetch all resources separately to find what it's looking for. Please see proposal above for a dedicated tilesets property in the {collectionId} resource, or alternatively keeping /tiles a requirement, linking to that, and having that tilesets property in there.

Also relation type tiles does not seem accurate, it should be a tileset singular, and if the way agreed upon are full URLs then Clemens proposed http://www.opengis.net/def/rel/ogc/1.0/tileset above.

joanma747 commented 4 years ago

I was too fast in writing my last comment.

The current wording in the stadandard candidates represents this status: A tileset SHALL be linked directly from the resource .../tiles/{timematrixsetid} (rel tiles) If the resource is dataset or a collection this is a vector tile If the resource is a map this is a map tiles. It contains the style: map/{styleId}/tiles/{timematrixsetid} (rel tiles) (I do not not know about coverages. .../coverage/tiles/{timematrixsetid} ? )

I believe this addresses your bullet one and three. Bullet two could be addressed by bringing back the full description in the optional tilesets resource.

About the relations type that points to a single tileset a respectfully disagree. The relation type is not the target type. A relation type expresses the intention of the relation. In my opinion, the relation is done to provide access to tiles (plural) and then a tile is an 'item' or 'tiles'.

jerstlouis commented 4 years ago

@joanma747

A tileset SHALL be linked directly from the resource .../tiles/{timematrixsetid} (rel tiles)

That sentence is confusing... Isn't that the URL of the tileset itself? e.g. http://data.example.com/collections/buildings/tiles/WebMercatorQuad available as both OGC Tiles default JSON and TileJSON. Does this mean to say that it is linked directly from e.g. ../{collectionID} or ../{collectionId}/map ? Maybe that was columns of a table.

If the resource is dataset or a collection this is a vector tile If the resource is a map this is a map tiles. It contains the style: map/{styleId}/tiles/{timematrixsetid} (rel tiles) (I do not not know about coverages. .../coverage/tiles/{timematrixsetid} ? )

This relies on parsing the href link to determine the style, which is cumbersome and might not work if your implementation decides to host that at another URL for some reason (e.g. static server hosted elsewhere to save costs). With changes we have discussed in Coverages recently, /coverage is the coverage itself, and there would be no other place than {collectionId} to link the tileset from. Up until recently it wasn't clear yet whether /map would be an actual default map right away, in which case it would have suffered from the same problem. Note that you still want a way to be able to list the styles that work with a collection without using the map resource (e.g. for client-side rendering).

Bullet two could be addressed by bringing back the full description in the optional tilesets resource.

I think that a short listing of the tilesets, including the TMS they're for and the style they represent (for maps) is essential, so it cannot rely on an optional thing. So why not make the /tiles resource that proper list of tilesets, more or less as described above (without the tiles templates links, detailed tileMatrixSetLimits or layers description, that will only be in each individual tileset), and the {collectionId} resource can simply have a link to that?

The relation type is not the target type. A relation type expresses the intention of the relation.

I understand that, but I think we have been pushing this too far, to a point where this is over-complicating things and making everything super confusing. While a very relation relation type like self, alternate, item, parent might make sense, when there is no clear, unambiguous relational way to describe what you get, it is so much clearer to describe what you will get if you follow that link. We could debate that this is still a relation. The Coverages draft have a nice clear table identifying the paths, associated relation type, and description of the resource. Both in the current master branch and the Pull Request I have been working on where I propose to assign a specific relation type to each resource. Having a clear relation type to link to a Tileset, rather than using tiles or item for both tileset and tiles, is much easier for developers to understand and implement correctly. Singular tile I think is wrong, because although a single tile resolves to one tile, being a template, the template itself expresses a relation to many tiles.

Another point: we have discussed multiple times the possibility to have a stand-alone Tiles API. One that would not rely on Coverages or Features or Maps. Having a list of well-described tilesets, either at /tiles, which can be linked from {collectionId} resource, or directly in the {collectionId} resource, achieves this, while being able to deliver tiles for any or all of Coverages, Features and Maps.

One would only need to conform to OGC API - Tiles, but still have the capabilities to deliver vector tiles, coverage tiles and/or map tiles.

However this should not prevent the ability to also provide links to tilesets from other resources, e.g. /map/{styleId}/tiles can still be defined in Maps as returning a list of tilesets for that styled map resource.

pomakis commented 4 years ago

I agree that a tileset should be an addressable resource (rel=ogc:tiles:tileset). In CubeWerx's current implementation, example tileset URLs would be:

https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/collections/AgricultureSrf/tiles/smerc?f=json https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/collections/AgricultureSrf/map/Night/tiles/smerc?f=json

These URLs currently return 404 because we haven't implemented such endpoints yet, but I agree that it makes sense to.

Furthermore, any resource that is a set links to tilesets would be a tilesets (rel=ogc:tiles:tilesets) resource. I think we're all on the same page up to this point.

What I still don't agree with, though, is the suggestion that all of the available tilesets (data and map alike, for all styles) be lumped together in a single tilesets resource (either inline in a collection resource or linked from a collection resource), and then distinguishing them internally via "dataType" and "style" properties. It seems more natural to me to put the tilesets resource listing the available data tiles at collections/{collectionId}/tiles, and to put the tilesets resource listing the available map tiles for a particular style at collections/{collectionId}/map/{styleId}/tiles. The collections/{collectionId} resource would still provide a rel=ogc:tiles:tilesets link to collections/{collectionId}/tiles, but it would be for the data tiles only. The links to the map-tile tilesets would be in the collections/{collectionId}/map metadata resource, with one tilesets link per style. (The collections/{collectionId}/map/{styleId} endpoint can't report this link because it's the map-generating endpoint.) This is what our current implementation does:

https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/collections/AgricultureSrf/map?f=json

Since we're trying to allow a collection to have both vector and coverage data tiles, you may argue that we still need the "dataType" property describing a tileset link so that vector data tilesets can be distinguished from coverage data tilesets. Although I'm of the opinion that we don't need a separate collections/{collectionId}/coverage/tiles endpoint for coverage data tiles. A single tileset can adequately handle a mixture of vector and coverage data tiles. If the tile format is "application/vnd.mapbox-vector-tile" or "application/geo+json", then they're obviously vector data tiles, and if the tile format is "image/tiff", etc., then they're obviously coverage data tiles. I see no need to split them into different tilesets.

pomakis commented 4 years ago

FYI, I've started a test implementation of tileset resources. E.g., the following will now return something:

https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/collections/AgricultureSrf/tiles/smerc?f=json https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/collections/AgricultureSrf/map/Night/tiles/smerc?f=json

However, I haven't yet adjusted our tilesets resources to provide links to these tileset resources, and probably won't until we've come to some sort of tentative agreement as to what and where these tilesets resources should be.

jerstlouis commented 4 years ago

@pomakis Our GNOSIS Map Tile format supports all of images, vector and coverage data in the same format, we could not rely on media type to discern them. So would something like GeoPackage tiles or any other container. "image/tiff" could also be either coverage or map tiles as GeoTIFF (though I guess that would not be an issue directly from the {collectionId} end-point.

As stated earlier, we would need a single tiles resource where all tilesets are available (e.g. from {collectionId}/tiles) to handle the stand-alone Tiles API client / server, that can rely simply on the Tiles API (independently of Maps, Coverage or Features API) to retrieve any of this (an example use case: a simple tiled GeoPackage producer).

However this should not prevent being able to list tilesets only for maps at /map/tiles, or only for a specific style at /map/{styleId}/tiles.

Also, in the Modular OGC API Workflows approach described in https://github.com/opengeospatial/wps-rest-binding/issues/47#issuecomment-664508833, we define a mechanism by which POSTing to a process an execution document can return a Tileset, for which accessing a tile may trigger processing. Those tiles could be any kind of data or rendered map tiles, and a mechanism to specify the kind of tiles for each of the available tileset would be very handy as well. The process may even result in multiple tilesets, e.g. both an elevation and orthorectified imagery tiles.

jerstlouis commented 4 years ago

@joanma747 @pomakis @cportele I have updated our implementation to reflect the latest suggestions with a tilesets list at .../{collectionId}/tiles and a tileset at .../{collectionId}/tiles/{tileMatrixSetId}, and a link (from a plural tilesets relation type) from the collection:

https://maps.ecere.com/ogcapi

I have not yet included the map tiles at that /tiles (those are currently at /map/{styleId}/tiles), mainly because that would be a lot of tilesets for all styles X all tile matrix sets... But they might have to be there to really support a generic stand-alone Tiles API.

cportele commented 4 years ago

I do not really like the approach to have two separate JSON representations for a tile set (OGCs and TileJSON), largely with complementary content - and broken content negotiation as both do not have their own media type. Wouldn't it be better to define a single JSON response schema that covers the scope of both. It would be seen by TileJSON clients as valid TileJSON 2.2.0 (or 3.0.0 draft) and they would ignore the limits etc. We don't even have to make a normative reference to TileJSON or talk about it (maybe just add it in the bibliography), it will just work.

jeffharrison commented 4 years ago

@cportele said, 'I do not really like the approach to have two separate JSON representations for a tile set (OGCs and TileJSON), largely with complementary content - and broken content negotiation as both do not have their own media type. Wouldn't it be better to define a single JSON response schema that covers the scope of both?'

I would say, 'Yes, it would be better to define a single JSON response'

jerstlouis commented 4 years ago

@cportele @jeffharrison While I agree that the TileJSON and "OGC" JSON could potentially be merged into a single representation, I have a few concerns:

These concerns aside, what we end up with though are completely different set of properties for the TileJSON and the non-TileJSON approach, except for the vector layer fields which we are now proposing for both.

I worry about interoperability issues arising from this based on relying on the presence of a property from one or the other set (e.g. tiles template in links vs. single TileJSON-style template). Potentially this could be addressed by requiring all essential properties to always be present.

So basically we would be adding to the VTP2 TileJSON:

Two examples from our service here to picture it:

https://maps.ecere.com/ogcapi/collections/Daraa/tiles/WebMercatorQuad?f=json

https://maps.ecere.com/ogcapi/collections/Daraa/tiles/WebMercatorQuad?f=tilejson

cportele commented 4 years ago

@jerstlouis

The necessity of multiple representations using the same base encoding format (e.g. JSON, XML, PBF...) but a different schema, for which a specific media type has not yet been defined is going to be faced again and again, and this is not a general solution to that problem. It should be possible to either define a new media type when needed and/or to specify an attribute for a schema used with the encoding.

It is straightforward to register new media types with IANA. A bit more work to register media types for formats specified in OGC standards in the IANA standards branch, quite simple to register any kind of media type with some specification in the vnd or prs branch.

The TileJSON being defined by Mapbox, although indeed there is no need to reference and the specifications license allows to derive from it, are there any related concerns about this?

Good question, I hope not, but we will find out.

How will multiple alternate template links for different formats be allowed? Potentially an extra links property could do this...

Not sure what the issue is, unless it is the next point:

Note the use of {tileMatrix}, {tileRow}, {tileCol} vs {x}, {y}, {z} in TileJSON as well. And the fact that WMTS and {tileMatrix} so far could still have a been text rather than an integer (though I have always preferred limiting to integers personally).

Ah, the different template parameters are really an issue. That would seem to require that both templates are in the document, which is not really optimal. I need to think about that a bit more.

jerstlouis commented 4 years ago

@cportele

Not sure what the issue is, unless it is the next point:

Yes, that next point, but also the ability to enumerate more than one supported format with one template per link (as may be required for implementing a static server that supports more than a single format).

If the proper solution is to register a new media type, whatever that type has to be, I don't think we should shy away from that just because they're both encoded as JSON.

cportele commented 4 years ago

If the proper solution is to register a new media type, whatever that type has to be, I don't think we should shy away from that just because they're both encoded as JSON.

I agree. My point about merging both JSON documents is mainly about the fact that these are not really alternative formats, but clients may want to have information from both, because the content is complementary, so it seems better to merge the content into a single JSON document.

jerstlouis commented 4 years ago

@cportele Well my impression from first learning about TileJSON in depth during the pilot and to some extent until now, is that the Tiles API OGC JSON is geared towards more native OGC services and its lineage can be traced back to WMTS, whereas the TileJSON really exists to accommodate the users of Mapbox tools.

As I was pointing out, there was no overlap at all between the properties until we discussed adding the vector layers fields information to the OGC JSON. Even though they sort of express the same things, they did so in different ways, characteristic of the communities they're coming from, like zoom levels vs. tile matrix etc., so I would argue that mostly they are more alternative ways of expressing the tileset than complementary...

But that's distinction might be a bit fuzzy, and of course the more we make the OGC JSON look like the TileJSON, the less this is true.

mcechini commented 4 years ago

In the interest in closing out this specific issue, do we need to resolve this "TileJSON vs "OGC" JSON topic? As I understand our conversation from yesterday, I don't think we do since we're debating response format vs API paths/references/conformance classes. And if not, can we create a new issue where that topic can be debated and resolved... while we move forward with updating the spec and examples and our sample implementations according to the structure decided on yesterday for this issue specifically?

... But if we do need to solve the JSON format issue... carry on... (My 2 cents is that the two formats is acceptable. One is a more "native" definition matching the rest of the OGC Tiles API spec and the other is an alternative for clients that are more MapBox aware)

jerstlouis commented 4 years ago

@mcechini agreed this is a separate issue.

To resolve this issue we need to agree on a base list of tilesets conformance class, which is simply a tilesets property which can be part of the response at .../collections/{collectionId}/tiles (GeoData-TilesetsList) and {datasetAPI}/tiles (Dataset-TilesetsList) derived conformance classes, using the same schema. In addition, links to alternate lists of tilesets could also be included so as to connect different types of tiles to all be reachable from only knowing about the /tiles resource.

Instead of simply a link, the objects referencing a single tileset would be a Tileset object, with a few new properties like style, dataType, as well as the tile matrix set indicators discussed in https://github.com/opengeospatial/OGC-API-Tiles/issues/47.

We also discussed the tileset description in the array at /tiles/ would be a subset of what one would find within the full tileset description resource at e.g. /tiles/WebMercatorQuad. TileMatrixSet limits and vector layers descriptions are things one would omit in the list of tilesets and only have in the individual tilesets.

I also believe a dedicated /tiles resource is necessary both because it may contain a lot of things and we don't want to make the collection too heavy, and because it allows this conformance class to stand on its own without a collection or dataset API. In particular this is useful for the modular workflows approach described in https://github.com/opengeospatial/wps-rest-binding/issues/47.

mcechini commented 4 years ago

ok, then perhaps @cportele can file that separate issue for the "TileJSON vs "OGC" JSON topic.

Here are some questions to start...

  1. What are the proposed values for dataType? (Note that I would be willing to accept a preliminary list and we can file a separate issue to revisit that list once we get something working)
  2. Is dataType required? If not, how should a client interpret that?
  3. Is style required? And if it is... then that would mean that the /collections/{collectionId}/tiles response will have an entry in tilesets for each unique combination of style and tilematrix. In the sample ecere implementation, that's 8 entries per style. Yes?
  4. Is there a way (perhaps in /api ?) to indicate to a client whether {datasetAPI}/tiles is supported, or must it always be supported... and if so, then what would we suggest a server put there? A list to every /collections/{collectionId}/tiles resource? (I suppose this could be it's own issue as well)

FWIW... as we hone in on the proposal, it would be very helpful to me if there was a repo branch with changes to the spec and quick start that match. That way we can just approve and merge a PR after we all agree to the changes. I'm not sure who usually does that and/or how it's approved.

jerstlouis commented 4 years ago

@mcechini

  1. So far I had proposed values (raw data values / coverages), image (maps or (A)RGB visualization-ready imagery mosaic) and vector (features / vector tiles)
  2. I would recommend it be required. Otherwise it would have to default to something... images?
  3. Style is not required, and should only be there for images (although some would argue it would make sense for vector data as well if the style drives filtering of features). If images and no style, the client must assume this is the default style and/or only style available. How I implemented this in our GNOSIS map server is that at .../{collectionID}/tiles?f=json I only directly include the raw coverage tiles (we have 8 TMS, so 8 of them), then I have in the links a link to the default map style. At e.g. the .../{collectionID}/map/default/tiles?f=json again I only have the night tilesets in the tilesets property, but have in the links a link to the tiles for each other styles, plus a link to the raw coverage tiles at .../{collectionID}/tiles. The linking idea was there could be some flexibility in how the server sets this up, as long as all availlable tilesets are somehow reachable from that /tiles end-point.
  4. A link with specific tilesets (plural) relation type from either a {collectionId} or a {datasetAPI} should provide a resource which corresponds to /tiles. The path might not need to be fixed. The conformance class corresponding to each is Geodata-TilesetsList and Dataset-TilesetsList. A server may also only implement a generic TilesetsList which is not tied to either a collection or a dataset (at which point the client would start discovery at the TilesetsList resource.

Agreed that it would be useful to set up a branch with these changes... I believe @joanma747 normally does this... I think at this point we are still trying to get everyone (Joan included) to understand the proposed changes, and thank you for your great questions because I think answering these is very helpful for that! As Joan mentioned yesterday the devil's in the details.

jerstlouis commented 4 years ago

@mcechini @joanma747 @cportele @pomakis @ghobona As part of working on an OpenAPI definition for Modular OGC API Workflows (big thanks to @bpross-52n for getting me started with OpenAPI and SwaggerHub), I have set up some initial schemas for those tiles resources as proposed:

https://app.swaggerhub.com/apis/jerstlouis/MOAW/MOAW-0.1#/tileset

https://app.swaggerhub.com/apis/jerstlouis/MOAW/MOAW-0.1#/tilesetsList

https://app.swaggerhub.com/apis/jerstlouis/MOAW/MOAW-0.1#/tileMatrixSetLimit

https://app.swaggerhub.com/apis/jerstlouis/MOAW/MOAW-0.1#/vectorLayer

All of {datasetAPI}/collections/{collectionId}/tiles, {datasetAPI}/tiles, {datasetAPI}/map/{styleId}/tiles would return a tilesetsList response. {datasetAPI}/map/{styleId}/tiles/{tms} would return a tileset (which is also an array element of tilesetsList, but in that context omitting vectorLayers and tileMatrixSetLimits to lighten it up).

In the case of MOAW, POSTing a workflow to {serviceAPI}/processes/{id}/tiles and {serviceAPI}/processes/{id}/tiles/{tms} also return a tilesetsList or tileset, respectively.

I also have a Maps List resource at https://app.swaggerhub.com/apis/jerstlouis/MOAW/MOAW-0.1#/mapsList for what you would find at {datasetAPI}/map or {datasetAPI}/collections/{collectionId}/map (or with MOAW, {serviceAPI}/processes/{id}/map)

Joan please feel free to re-use any of this to update the Maps and/or Tiles specifications as you deem fit. My suggestion for the combined Maps / Tiles integration, is simply to have a MapsTiles conformance class for Tiles in Maps - Part 2: Data subsetting (in addition to bbox and/or subset) which references the Tiles tilesetsList conformance class.

Please have a look; a lot of this is functional with our sample server in the SwaggerHub generated client. I have not yet added the regular /collections resources yet though.

Thanks!

joanma747 commented 4 years ago

The changes proposed here by @jerstlouis are changes in the TMS2D standard, because they affect the tileMatrixSetLinks data model. I believe this UML diagram represents what @jerstlouis proposes reasonably and adopts some of the good ideas in TileJSON.

TileSet2D

If this is accepted I could start transposing this into a JSON encoding, swaggerhub examples and standard draft.

jerstlouis commented 4 years ago

@joanma747 I didn't realize / think that the TileMatrixSetLink class was defined in the 2DTMS, because this is not something that is defined in the JSON encoding of a TMS at least.

Is it possible that this is some superfluous stuff that ended up copied to the 2DTMS but really did not need to be there? Is it only that UML diagram?

In my opinion all those things in those diagrams are part of the Tiles API, but don't have to be defined in the 2DTMS.

joanma747 commented 4 years ago

This is the final agreement on the new data model for the TMS2D. The TMS2D will change title to "tilematrixset and tileset metadata". TileMatrixSetLinks will be superseded by Tileset. TileSet

jerstlouis commented 4 years ago

As @joanma747 clarified today, I think it is important to point out that the intent is to rename the "2D Tile Matrix Set Standard" to become the "2D Tile Matrix Set and Tilesets (metadata?) Standard", and having two separate conformance classes: one for defining Tile Matrix Sets, and one for defining Tileset metadata.

Until today, I was not aware that tileset metadata was within the scope of the 2DTMS and thought it focused solely on the TMS definition. This renaming and separation in two clear distinct conformance classes will greatly dissipate the confusion. @ogcscotts @cnreediii

It might also be useful to compare this with the tileset metadata model defined in VTP2 ( http://docs.opengeospatial.org/per/19-082r1.html#MetadataModel ), and clarify whether this Tileset metadata conformance class of 2DTMS & TS standard supersedes that.

@joanma747 @jeffharrison After comparing the two, in the context of a conformance class specifically for Tileset metdata, rather than simply a minimal Tiles API to get things working, it might be worth it to re-think this a bit and start from the VTP2 Tileset metadata and identify essential vs. optional elements, and anything that needs to be adjusted. A lot of efforts and consideration went into that during VTP2.

The main thing I would tweak from the VTP2 TilesetMetadata is skip the intermediate TileMatrixSetLink object so that the tileset (metadata) would point directly to the TileMatrixSetLimits and TileMatrixSetURI/Description (I still think think we need to maintain that distinction, unless we guarantee that the OGC URIs resolve to a definition and also allow an optional local defintion).

I see that a lot of the things we discussed today were resolved in that model: e.g. both minZoom and maxZoom (as strings) and min/max scale denominators are there; properties are called "featureAttributes".

I also wonder about how the 'links' fit within the context of offline tileset metadata? e.g. the VTP2 metadata had a dedicated tilesLocation property.

joanma747 commented 3 years ago

The TileSEtMetadata will be applied in TMS so let's continue discussions on this part there: https://github.com/opengeospatial/2D-Tile-Matrix-Set/issues/11

joanma747 commented 3 years ago

TileSetMetadata is agreed.

We agreed in 2020-12-09 members meeting that:

The \tiles endpoint will return a {"tilesets": [ (..TileSetMetadataobjects..) ]}