Is tileMatrixSetURI really optional?

[tschaub]

The current schema for a tileMatrixSetLink-entry looks like this:

  tileMatrixSetLink-entry:
    type: object
    required:
      - tileMatrixSet
    properties:
      tileMatrixSet:
        type: string
        example: 'WebMercatorQuad'
      tileMatrixSetURI:
        type: string
        format: uri
        example: 'http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad'

Is it intentional that the tileMatrixSetURI property is optional? If so, it isn't clear to me how a client is supposed to generate the tileMatrix for a tile request.

[jerstlouis]

This may be related to the idea that a "Core" supports 8 known TMS.
I believe that this approach is a mistake, and that a tileMatrixSetURI should not be optional.

Special conformance classes could require that the TMS be available from the OGC name authority, or could reference one or more specific TMS.

[tschaub]

Thanks for weighing in, @jerstlouis. I think we're thinking the same thing. Just to be clear, it seems to me that even if the core says that 8 known tile matrix sets can be used, those links should still include the tileMatrixSetURI as a way to identify those.

But it isn't clear to me whether the intention is that tileMatrixSet or tileMatrixSetURI be used to uniquely identify a tile matrix set.

[jerstlouis]

@tschaub Yes it could.
The original intent was that tileMatrixSet is the identifier alone, which can be used to look up a well known TMS from the OGC naming authority / TMS registry.
The URI (which I don't think should be optional) in any case could either point to the server's own list of tileMatrixSets at /tileMatrixSets, or to the OGC registry.

It could be clarified that for the 'OGC Registered TMS', the identifier can be used together with a pre-determined OGC naming authority path.

And I argue against picking any 1 or 8 specific TMS as being "Core". A Profile can specify which one(s) is/are required. We don't want to be biased towards WebMercator, yet we do not want to put an overwhelming requirement on either servers or clients to have to support all 8 of an arbitrary selection of TMS.
(As it so happens, http://schemas.opengis.net/tms/1.0/json/examples/GNOSISGlobalGrid.json is not included in those 8 for some reason, yet it is a great TMS which is appropriate to any and all use cases, so I am a little biased ;) )

[pomakis]

Since a service can use arbitrary tile-matrix-set identifiers, and since a tileMatrixSetURI can't be guaranteed to be a resolvable URL, I think there's a requirement to add a wellKnownScaleSet field to tileMatrixSetLink-entry.

Even if the tileMatrixSetURI was guaranteed to be a resolvable URL, we certainly don't want to require the poor clients to fetch and parse the full tile-matrix-set definitions just to figure out what it is. How frustrating would the given example be to a client application?

{
"tileMatrixSet": "WorldMercatorWGS84Quad",
"tileMatrixSetURI": "http://schemas.opengis.net/tms/1.0/json/examples/WorldMercatorWGS84Quad.json"
}

Adding an optional wellKnownScaleSet field to tileMatrixSetLink-entry provides a reasonable solution to this.

{
"tileMatrixSet": "WorldMercatorWGS84Quad",
"wellKnownScaleSet": "http://www.opengis.net/def/wkss/OGC/1.0/GoogleMapsCompatible",
"tileMatrixSetURI": "http://schemas.opengis.net/tms/1.0/json/examples/WorldMercatorWGS84Quad.json"
}

Now the client everything it needs to know without having to hunt down and parse
the full definition of the tile-matrix set.

[jerstlouis]

@pomakis Multiple TileMatrixSets could use the same WellKnownScaleSet, but differ in how the tiles are cut or on the pixel size of the tiles...

The tileMatrixSet is intended to be the mechanism by which to recognize it, if it is one of the OGC NA registry then perhaps it should be clarified that those identifiers are reserved?

Or perhaps the tileMatrixSetURI should always point to the OGC NA registry, rather than the one on the local server?

[jerstlouis]

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 / is an identifier (stripping any ?query parameters), which must match the TMS name in the 2D-TMS standard if it 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).

[jerstlouis]

@pomakis I noticed at https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/collections/Daraa_DTED/tiles?f=json you have:

{"tileMatrixSet":"smerc","tileMatrixSetURI":"https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/tileMatrixSets/smerc?f=json" }

Which would not be compatible with the core capability of pre-defined TMSes, and would force a client to parse the full TMS (if it supports that capability).
If using a common standardized defined in the TMS standard, it should be easily recognizable by the client.
Again the specifications are confusing on all this (some things will have to change anyways though e.g. #43 ).

[pomakis]

@jerstlouis, are you suggesting that it should instead report "http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad" as the tileMatrixSetURI?

That makes a certain amount of sense, since it allows the client to (potentially) know all of the details of the tile-matrix set without having to fetch and parse its definition. I still think it'd be useful to indicate the well-known tile-matrix-set here as well. This information can be implied by the tileMatrixSetURI, but if and only if it's one of the standard tileMatrixSetURIs and the client has hardcoded knowledge of the standard tile-matrix sets. And of course, it's still necessary to provide the client with a link to the actual definition of the tile-matrix set. In light of all this, perhaps (for now at least), I'll adjust our output to report:

  "tileMatrixSetLinks": [
    {
      "tileMatrixSet": "smerc",
      "tileMatrixSetURI": "http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad",
      "wellKnownScaleSet": "http://www.opengis.net/def/wkss/OGC/1.0/GoogleMapsCompatible",
      "definition": "https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/tileMatrixSets/smerc?f=json"
    }
  ]

Then we can discuss what the "OGC API - Tiles" standard should say.

[jerstlouis]

@pomakis well in #43 (comment) I am suggesting a number of changes.

That makes a certain amount of sense, since it allows the client to (potentially) know all of the details of the tile-matrix set without having to fetch and parse its definition

That is something that the Tiles core conformance classes requires. Tiles clients that only support Core are not expected to support the more advanced TMS description conformance class which enables a custom TMS that needs to be parsed.

Now with the latest conformance classes direction, we are talking about a TileSet resource, which is always for a single TileMatrixSet, so the tileMatrixSetLinks property does not make sense anymore.

And in that suggestion, I was suggesting to fuse tileMatrixSet and tileMatrixSetURI into a single tileMatrixSet property, since as I mentioned they are both "identifiers".
So you would have a single (Option 1):

...
   "tileMatrixSet": "http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad"
...

which is really all you need. This could also be:

...
   "tileMatrixSet": "http://test.cuberwerx.net/ogcapi/tileMatrixSets/WebMercatorQuad?f=json"
...

And that would be a resolvable URL, which returns you the definition in either case, acting both as the URI and the definition.
This allows it to be a custom TMS without different mechanics.

And it would have to end with WebMercatorQuad in either case, if it represents the GoogleMapsCompatible TMS.
And a client could just recognize that last name (any query parameters like ?f=json would be stripped), as any name defined in the TMS should represent exactly that TMS.

An alternative (Option 2) would be to have:

...
   "tileMatrixSetURI": "http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad",
   "tileMatrixSetDefinition": "https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/tileMatrixSets/WebMercatorQuad?f=json"
...

where tileMatrixSetURI is required and should be used only when your TMS is one defined in 2D-TMS or registered with the OGC.

Or simply (Option 3):

...
   "tileMatrixSet": "WebMercatorQuad",
   "tileMatrixSetDefinition": "https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/tileMatrixSets/WebMercatorQuad?f=json"
...

with similar rules.
I think I prefer Option 3 best.

About the wellKnownScaleSet, that is already included in the TMS definition.
Knowing the WKSS alone does not really help the client by itself, as a TMS could be defined with a not well known scale set, and multiple TMSes could be defined using the same WKSS. But there's probably no harm if the server wants to include that there as well.

[pomakis]

@jerstlouis, are you suggesting that if a server has a tile-matrix set that's compliant to "http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad" (OGC 17-083r2, Annex D.1), it cannot use a server-specific ID (such as "smerc") for it, and instead must use the the ID "WebMercatorQuad"? This will be quite problematic when trying to add OGC API endpoints to existing WMTS services, which always use server-specific tile-matrix-set IDs (even for the common case of WebMercatorQuad tile-matrix sets). I'm not saying that this is a show-stopper for your suggestion, just that the incompatibility with existing services shouldn't be taken lightly.

Either way, I don't think options 1 and 2 are feasible. If I understand your suggestions, they would require the client to parse the short-identifier string (e.g., "WebMercatorQuad" out of a URL such as "http://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/tileMatrixSets/WebMercatorQuad?f=json". The short identifier needs to be explicitly reported (as in option 3).

But I'm worried about the equivalance drawn between the short identifier (e.g., "WebMercatorQuad") and the full-URI identifier (e.g., "http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad"). The reason why we use full URIs as identifiers nowadays is to allow for different authorities, etc. E.g., "http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad" can be a separate and distinct tile-matrix set from "http://www.cubewerx.com/def/tilematrixset/CubeWerx/9.4/WebMercatorQuad". (Otherwise, what's the point of even using full URIs as identifiers?) But we want short identifiers so that our endpoint paths don't get crazy. E.g., we want

  http://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/tileMatrixSets/WebMercatorQuad

not

http://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/tileMatrixSets/http%3A%2F%2Fwww.opengis.net%2Fdef%2Ftilematrixset%2FOGC%2F1.0%2FWebMercatorQuad

Which is why server-specific short identifiers are nice.

So I propose an Option 4:

   "tileMatrixSetId": "smerc",
   "tileMatrixSetURI": "http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad",
   "definition": "https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/tileMatrixSets/smerc?f=json"

where "tileMatrixSetId" is required (and is to be used to resolve the {tileMatrixSetId} variable in the tile-URL templates, etc.), and where "definition" is required unless "tileMatrixSetUri" is present and is one of the standard URIs in OGC 17-083r2 Annex D. Yes, both "tileMatrixSetId" and "tileMatrixSetURI" are identifiers, but the former is a local short identifier, and the latter is a global well-known identifier.

I also propose an optional "wellKnownScaleSet" property. It's very useful for a client to be able to accept or reject a tile-matrix set for use based on this property (without having to infer it from the tileMatrixSetUri or to parse the definition for it).

(As an aside, I just noticed that the well-known-scale-set URIs have changed between WMS 1.0 (OGC 07-057r7) and OGC 17-083r2. In the former it's "urn:ogc:def:wkss:OGC:1.0:GoogleMapsCompatible", while in the latter it's http://www.opengis.net/def/wkss/OGC/1.0/GoogleMapsCompatible". What a pain! So much for a simple string comparison!)

[jerstlouis]

@pomakis About server-specific "tileMatrixSetId" (e.g. smerc), I think this particular identifier should be standardized (i.e. WebMercatorQuad) if you implement OGC API - Tiles with this prescribed default JSON encoding of the Tileset (note that you could define your own custom encoding, or use TileJSON instead to describe the TileSet).

However, you would be free to use smerc in your tiles template:

"https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/dted/map/night/tiles/smerc/{tileMatrix}/{tileRow}/{tileCol}?f=png",

which could even directly link an existing WMTS server in that link, so I think this addresses your concerns (and make Options 1,2 and 3 valid, which comes down to URI vs. definition vs. identifier preferences).

[pomakis]

@jerstlouis, how could one be free to use an unadvertised local tile-matrix-set identifier in the tile-URL templates? The templates have a {tileMatrixSetId} varaible that needs to be resolved by the client. E.g., https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/collections/Daraa_DTED/map/Night/tiles?f=json returns:

  ...
  "links": [
    {
      "href": "https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/collections/Daraa_DTED/map/Night/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{ti
leCol}",
      "templated": "true",
      "rel": "item",
      "type": "image/jpgpng",
      "title": "JPEG or PNG image tiles"
    },
  ...

[jerstlouis]

@pomakis just drop the {tileMatrixSetId} variable, because with the new conformance classes reorganization (see #43 (comment)), we are talking about a resource describing a single Tileset (for a single TMS, like with Mapbox TileJSON).

In issue 43 we agreed to no longer require the /tiles resource at all, so clients would not use it (though the server may still provide it to facilitate browsing through).

[pomakis]

@jerstlouis, Hmmm, okay, I think I understand. The way I think best is to dive into an implementation and see where it takes me, so that's what I'll do.

Either way, I don't think option 1 is viable, because the URI isn't guaranteed to be resolvable, and you can't expect the client to sniff short-identifier names (such as WebMercatorQuad) out of the URI to try to determine whether it's one of the pre-defined ones.

If I manage to convince myself that a short local identifier isn't required, then the minimum you really need to report is the tileMatrixSetURI (for pre-defined tile-matrix sets):

  ...
  "tileMatrixSetURI": "http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad",
  ...

or the tileMatrixSetDefinition (for custom tile-matrix sets);

  ...
  "tileMatrixSetDefinition": "https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/tileMatrixSets/smerc?f=json",
  ...

I.e., there's no need to report a tileMatrixSetDefinition for pre-defined tile-matrix sets, and there's no need to report a tileMatrixSetURI for custom tile-matrix sets.

[pomakis]

@jerstlouis, re: not requiring the /collections/{collectionId}//tiles resource, I think it would be a shame
to throw all of that stuff into /collections/{collectionId} (and having to add a "dataType" field, etc.). I kinda like /collections/{collectionId} being short and sweet. Our current implementation has /collections/{collectionId} reporting this link for data tiles:

    {
      "href": "https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/collections/Daraa_DTED/tiles?f=json",
      "rel": "tiles",
      "type": "application/json",
      "title": "data tiles of this collection"
    }

and this link for maps:

    {
      "href": "https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/col
lections/Daraa_DTED/map?f=json",
      "rel": "maps",
      "type": "application/json",
      "title": "map layers and tiles of this collection"
    },

where this "maps" resource provides the set of available styles, and a number of
links for each style including one for map tiles (if available):

    {
      "href": "https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/collections/Daraa_DTED/map/Night/tiles?f=json",
      "rel": "mapTiles",
      "type": "application/json",
      "title": "map tiles in the \"Night\" style"
    },

I also like the idea of (in general, where it makes sense) having every element in a path be some sort of defined resource in its own right. So if we're defining /collections/{collectionId}/tiles/{tileMatrixSetId}/... endpoints, it'd be nice to have /collections/{collectionId}/tiles be a metadata endpoint that describes everything under it. Why stuff all of this into /collections/{collectionId} and leave /collections/{collectionId}/tiles undefined? Wouldn't it be nice to have am independent "tiles" resource to refer to and pass around? 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.

[jerstlouis]

@pomakis About the tileMatrixSet URI / identifier that this issue is about...

• I would argue that the tileMatrixSetDefinition should always be required, allowing e.g. a client to rely on parsing the definition if that is how they decide to implement it.
• For the tileMatrixSetURI, I believe this should be required to be resolvable, and I think we had agreed on that (when online of course). Otherwise, why are we wasting precious bytes and parsing time with an http:// prefix etc., instead of e.g. ogc:tms:WebMercatorQuad if we really want it org-specific?
• I think a unique simple names across all organization is a big advantage, there's no limit to 4 or 5 digits here, for a very custom TMS people can prefix the TMS name with their org name, and anyways the identifier or URI is only for standard OGC TMSes in the first place.
• And I believe (I might be wrong) that the original intent was that the URI resolves to a TMS definition. Which brings the question of why are these two separate things at all? (Argument for Option 1 rather than Option 2)
• And if we are using a full URI with an http protocol and server etc., if a client internally uses TMS names which do correspond to the official ones defined in the TMS standard and the OGC registry, it still needs to either extract the last part of the URI to compare it, or add that ugly http URI in the code to be compared against. The only advantage of that full http URI would be to accommodate different organizations defining different TMS with the same names, which as I said I think is something that should be avoided at all costs. Anyways as you mentioned, the URI identifier is only for when using an official 2D-TMS standard TMSes (or potentially one that is registered with the OGC's official TMS registry). So I don't see a need for that full http URI, unless it also doubles as a resolvable TMS definition, and a client can also reliably extract the last piece of it to recognize a standard or OGC-registered TMS.

To recapitulate:

• Option 1 has a simple single property (acting as both the definition and the identifier), relies on the client extracting that last part of the URI
• Option 2 relies on either extracting or comparing a long ugly http string (the servers & clients have to maintain 2 separate identifiers, one with http://... and one without)
• Option 3 . The identifier is a simple string the server can readily use (e.g. in its URL paths, if it wants to) and compare to known TMS, and for the definition a server can decide to point to the authoritative OGC TMS definition which will always be resolvable. This could also be required for a standard TMS, and there could also be an alternateTMSDefinition which point to the local server's own TMS definition.

Your last suggestion is closest to Option 2, but for these reasons my preference still lies with Option 3.
Feedback on this from @joanma747 and @cportele would be welcomed.

Regarding the /tiles end-point discussion, removing it was the result of a SWG decision on July 16th. To clarify, it could be specified (it provides a list of tilesets), but not required. I will reply to your comments in more details in #43.

[mcechini]

My 2 cents:

• The required identifier allows for simpler identification of a TMS... either because it's one of the 8 core TileMatrixSets or a custom TileMatrixSet. I don't think there is much conflict on this one.
• Requiring tileMatrixSetDefinition ensures that information for the TileMatrixSet is always available, even if not needed by the client (but there's lots of info they already ignore anyway). A server then can provide the definition for their custom TMS or point to the official OGC endpoint definitions of the 8 core TileMatrixSets.
• Providing an HTTP URL (e.g. http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad) for the URI that doesn't resolve seems confusing and redundant when you could just require that the identifier be something URI-esque like "ogc:tms:WebMercatorQuad"

[jerstlouis]

@mcechini I agree wholeheartedly with everything you said (except that there are now more than 8 standard TileMatrixSets resolvable by identifier!).

However I believe there has been a OGC Naming Authority decision that all URIs be http. Especially if those are not guaranted to resolve as soon as they are accepted, I disagree strongly with that decision.

I really don't understand why you would specify a URI prefixed by http and a long domain name and path which is not guaranteed to be resolvable, it is as you point out super confusing and cumbersome and waste precious bytes.

[ghobona]

@mcechini The URIs of all Tile Matrix Set (TMS) definitions in the 2DTMS standard will have been configured to resolve by the time OGC API - Tiles is approved.

[mcechini]

Thanks for the clarification Gobe. So then we have...

• TMS Identifier: Shortname
• TMS URI: Resolvable URL
• TMS Definition: Full definition

My thoughts are now thusly...

I vote to require the Identifier and Definition. Identifier is clearly needed. Regarding the definition, servers using official 2DTMS TMSs already have the URL needed and if they are using their own TMS... they should have that definition available somewhere.

I vote to not require the URI. This feels like "extra credit" for a server to provide as information for the TMS. Best practice, especially if using an official 2DTMS TMS, would be to provide the official URI in this field. That would let a client easily identify known TMS' and avoid parsing the definition unnecessarily. To @pomakis's point above, I think we want to give a server the freedom to use their own Identifier, even if they are using an official 2DTMS TMS.

[jerstlouis]

@mcechini I disagree strongly with not requiring the official URI and allowing custom identifiers, and I also disagree with requiring the full definition (unless that full definition also happens to be the official or custom http URI, resolvable to a TMS definition).

This prevents quickly recognizing the identifier before fully parsing the lengthy TMS description, and prevent interoperability with clients not implementing the parsing of the definition (i.e. all clients implementing only the Tiles - Part 1: Core).

As discussed with @pomakis , being forced to use official identifier does not prevent the actual link to contain another TMS identifier, as it does not need to be a variable.

[mcechini]

Understood, and I see that conversation more clearly now from above... I don't have heartburn with enforcing specific identifier values then.

As for requiring the full definition... I do think that that "that full definition [should] be the official or custom http URI, resolvable to a TMS definition)."

From our perspective, a majority of our usage will not utilize an official 2DTMS TMS... so the URI field has little utility. We can choose a value to go there if needed, but the identifier (for purposes of referencing in tile requests) and definition (for purposes of the client understanding the TMS) are the salient details we need to provide.

[pomakis]

Until we get this sorted out, our test implementation identifies a tile-matrix set with the following fields:

  "tileMatrixSetId": "smerc",
  "tileMatrixSetURI": "http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad",
  "tileMatrixSetDefinition": "https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa/tileMatrixSets/smerc?f=json",
  "wellKnownScaleSet": "http://www.opengis.net/def/wkss/OGC/1.0/GoogleMapsCompatible"

I really like having a short local identifier, although I concede that we could probably get away without it as long as we avoid any possibility of introducing a "tileMatrixSetId" query or URL-template parameter.

Having an optional global identifier (URI) is a must. If the client can quickly identify it as one of the standard 2DTMS tile-matrix sets, it can avoid the costly task of parsing the definition. (In fact, I suspect the average quick-and-dirty client application will be incapable of parsing definitions.) But under no circumstance should we require (or even suggest) that the client parse anything out of this URI. It should be fully opaque (but presumably resolvable).

The definition URL should be required. If it's not one of the standard 2DTMS tile-matrix sets, parsing this definition is the only way a client will be able to properly interoperate. In theory, if we require the global identifier URI to resolve to the definition of the tile-matrix set, a separate definition URL would be redundant. But I don't have a lot of a trust in third-party (OGC in this case) URLs being guaranteed resolvable at all times, so a definition URL pointing to a local definition of the tile-matrix set would be much more reliable.

Finally, we've found a lot of value in advertising the wellKnownScaleSet (if any) of a tile-matrix set. It's a quick way for a client to weed through the options for one that at least matches the scale set it's looking for (typically, in our experience, GoogleMapsCompatible).

[jerstlouis]

@pomakis I would have liked a short global identifier instead of the http URI, but seems like everything is moving towards long http URI and that's the way it is, so I will have to live with that.

Having both tileMatrixSetId local and tileMatrixSetURI global is somewhat confusing, and not needed for either enumerating all avavailable tilesets, or for returning a particular tileset, now that we have a dedicated tileset resource. So let's drop it from this part of the specs at least to avoid that confusion, though a server could still specify it.

A {tileMatrixSetId} is still useful in the context of skipping this list of tilesets (.../tiles) resource and going straight to a tileset resource in a TMS you know the server supports (e.g. from {serviceAPI}/tileMatrixSets). We are also finding a use case for this in deferred / tiled distributed processing, where you would POST to .../processes/{processId}/tiles/{tileMatrixSetId} to directly retrieve a process-triggering tileset description.

I don't see any harm with a server adding a wellKnownScaleSet, but don't think this needs to be in the Tiles API specs -- most clients will stop at recognizing the tileMatrixSetURI, and all the common GoogleMapsCompatible / WebMercatorQuad use cases fall in this category. If anything, I think the 2DTMS description could potentially be where the wellKnownScaleSet is specified, since this is really targeting clients that support parsing the TMS definition.

Clients understanding the 2DTMS description part will likely only do so for custom TMS, and would likely be ready to handle any scale (and could always do a scale value comparison).

[mcechini]

Having both tileMatrixSetId local and tileMatrixSetURI global is somewhat confusing, and not needed for either enumerating all available tilesets, or for returning a particular tileset, now that we have a dedicated tileset resource. So let's drop it from this part of the specs at least to avoid that confusion, though a server could still specify it.

Jerome can you clarify what you mean in your last sentence above. I believe the rest of your comment is saying that both tileMatrixSetId and tileMatrixSetURI should be required fields, which I agree to. tileMatrixSetURI is the global identifier, while tileMatrixSetId is a shorthand reference that would be used in other Tiles API requests like these:

• /tileMatrixSets/{tileMatrixSetId}
• /collections/{collectionId}/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}
• /collections/{collectionId}/map/{styleId}/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}

As for whether tileMatrixSetId is a global vs local value... I lean towards local.

[jerstlouis]

@mcechini Well the essence of my comment is that tileMatrixSetId and tileMatrixSetURI with one being local and the other global is confusing, because that is two identifiers, and it is not clear from the name of these properties that tileMatrixSetId is a local identifier (I think that is the confusion that led to the creation of this issue in the first place).

So I was hoping we could do away entirely without the core specifications defining {tileMatrixSetId}.
The point is that all of these paths you just mentioned are not required to be fixed, so it is entirely up to the server what the value of {tileMatrixSetId} is, and the client should not have to replace a {tileMatrixSetId} within a template.

But if the server wants to define a local {tileMatrixSetId} as part of its API that should be possible (as long as a client does not need to replace it as part of the standard links defined in core), and one scenario in particular where I was considering its use is this deferred / tiled processing extension to submit a workflow for use with a specific TMS (this may also not have to be part of any core specs and could be an extension, as I had another more generic mechanism in mind requiring an extra GET...).

So, again to summarize, I don't think the specs should mention at all a {tileMatrixSetId}. The server is free to provide something like it.

[mcechini]

The more "but if a server wants to..." sort of things we allow, the less useful the specification would seem to be in helping both servers and clients define a clear set of rules for interaction.

I personally don't think requiring tileMatrixSetId is a big ask in addition to requiring tileMatrixSetURI. And if the local vs global issue is a concern (and I see your point)... then I would rather require specific values for tileMatrixSetId if a 2DTMS-managed TMS (and therefore tileMatrixSetURI) is used vs having tileMatrixSetId be optional.

[jerstlouis]

@mcechini The thing is that in the tilesets list and tileset resource, nowhere should {tileMatrixSetId} be used as part of a template. The tileset resource with the tiles URL template is now for a single tile matrix set.

That is because we explicitly decided that a tileset could be anywhere and follow any path structure at all, e.g. to be compatible with tiles published elsewhere or by other tools.

So there is no need at all for the specifications to specify a {tileMatrixSetId}.

e.g. my tileset tiles template URL might be http://mycheapstaticserver.com/buckets/123456/{tileMatrix}/{tileRow}/{tileCol}

[mcechini]

The thing is that in the tilesets list and tileset resource, nowhere should {tileMatrixSetId} be used as part of a template.

You lost me on that one. But maybe the fundamental issue I'm having with this is that I can't seem to find anywhere in the documentation where there is an example of how a client would interact with a server implementing the spec. For example...

1. Request /collections and look for X
2. Request /collections/{collectionId} and look for X
3. Request /collections/{collectionId}/tiles and look for X
4. Request /tilematrixSets/{tileMatrixSetId} and look for X
5. Request /collections/{collectionId}/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol} to get a tile

I see a number of folks standing up servers... but am I missing where there is information on how a client actually would trace through these URLs? This is the "what use cases are we trying to support" user scenario-driven approach.

[jerstlouis]

@mcechini
Based on the latest discussions in #43

1. Request dataset landing page and within links array property, look for relation type data (though this is fixed to /collections, so I would argue this can be skipped). You may also want to follow conformance to /conformance (also fixed) to verify that this dataset supports OGC API - Tiles.
2. Request that (/collections) and inside collections array property look for your collection of interest. In there, inside a links array property, look for a relationtype http://www.opengis.net/def/rel/ogc/1.0/tilesets (plural). The same information should also be available for that collection specifically at /collections/{collectionId}. Whether the tilesets links is required to be included at the /collections level should be clarified... Since it is a single link I don't see why it shouldn't be to avoid having to fetch yet a separate resource.
3. Request that, and in there within tilesets property, find your tileset of interest based on tileMatrixSetURI, dataType and (optionally for maps) style. Within a links property of that tileset, look for the http://www.opengis.net/def/rel/ogc/1.0/tileset (singular) relation type matching your desired tile set media type (e.g. JSON or TileJSON)
4. Request that (assuming JSON one), and in there within a links property of that tileset, look for a link with item relation type also matching your desired media type to find the tiles template URL.
5. Replace {tileMatrix}, {tileRow} and {tileCol} to access your tiles.
6. (Optional) in that tileset, use tileMatrixSetLimits to understand which tiles are valid without having to use the extent.

If you implement Part 2: Custom TMS, and the selected tile matrix set is not recognized as a built-in one:

7. Follow the tileMatrixSetDefinition property and parse the 2DTMS to know how to request and geo-reference the tiles.

I am a few minutes away from updating our server to match all this, a concrete example will help!

[jerstlouis]

@mcechini Example implementation of the latest suggestions at https://maps.ecere.com/ogcapi

[mcechini]

Thanks, however while an "example implementation" is helpful, an "example workflow / interaction patterns" is equally as helpful IMO. If the latter is convoluted, then we're not building a good spec.

[jerstlouis]

@mcechini I provided that that in the previous comment.

Are you finding that convoluted?

Note that this allows starting from any resource between step 1-5, which also correspond to different conformance classes:

1. landing page (which can be skipped) (Common-Core-Core),
2. list of collections (or single collection) (Common-GeoData-CollectionsList and Tiles-Core-GeoDataTileSets),
3. tilesets list (e.g. for a particular map style, or specifically vector or coverage data tiles) (Tiles-Core-TilesetsList),
4. specific tileset (for one particular tile matrix set) (Tiles-Core-Tileset), or
5. a URL template [https://maps.ecere.com/ogcapi/collections/blueMarble/map/tiles/WebMercatorQuad/{tileMatrix}/{tileRow}/{tileCol}.png],

and some tools already work with 4 (e.g. TileJSON format and Mapbox libraries) and 5 (e.g. OpenLayers).

[mcechini]

@jerstlouis Not at all saying what you have is convoluted. Just that as someone who's coming into this a little disjointed with the rest of you all... it's difficult to figure out what the user scenarios are for actual use of the API vs compliance checking with a spec.

What I'm probably saying is that the main page of the github project would benefit from with some real-world usage patterns that are updated along with the specification schema/document. There are links to sample implementations and swagger hub content, which are indeed helpful, BUT they don't necessarily help me know/evaluate the intended order of operations for a client.

[jeffharrison]

Yep, this is important for all new OGC APIs ---> 'knowing/evaluating the intended order of operations for a client'

Best Regards,
Jeff

[mcechini]

I'm not sure if this issue is resolved as a part of the discussion we had for issue #43. Either way, perhaps someone (I nominate @jerstlouis) could restate the current proposed change that could resolve this issue.

[jerstlouis]

@mcechini @pomakis

I propose that the following two properties be specified:

• tileMatrixSetURI: required when using a TileMatrixSet described in 2DTMS standard (Reminder: there are now more than 8!). This is a fully resolvable URI, which we do not yet know what it will resolve to. It could (should?) potentially resolve to a TMS definition. Example: "tileMatrixSetURI" : "http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad"
• tileMatrixSetDefinition: required when using a custom TileMatrixSet NOT described in 2DTMS standard. This links to a full TMS description according to the 2DTMS. Example: "tileMatrixSetDefinition" : "https://maps.ecere.com/ogcapi/tileMatrixSets/WebMercatorQuad".

A server could optionally add more properties if it wishes so, but I note that the known scale sets are already specified as part of the 2DTMS definition.

[mcechini]

Before I comment... I want to be clarify whether this applies to the /collections/{collection_id}/tiles/{tileset_id} resource as well as the tilesets property within the /collections/{collection_id}/tiles request? Or just the former?

[jerstlouis]

@mcechini I would say both.

[mcechini]

I'm ok with the proposal.

The part that I keep spinning over is this... In our current WMTS implementation, we define a number of TileMatrixSets that are all a subset of the larger (what is now) WebMercatorQuad TileMatrixSet. Each of our TileMatrixSets has a different number of TileMatrices depending on the layer resolution / tile pyramid size. How do we accomplish this in the Tiles API?

Option 1 ... Continue defining a separate TMS for each set of WebMercatorQuad zoom levels. The tileMatrixSetDefinition would contain the definition and reference the http://www.opengis.net/def/wkss/OGC/1.0/GoogleMapsCompatible WKSS. I don't think tileMatrixSetURI could point to http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad anymore, however we are still using that TileMatrixSet in a way. The /collections/{collection_id}/tiles/{tileset_id} response would potentially not need to specify the min/max zoom/levels because it'd be baked into the separate TileMatrixSets.

Option 2 ... Utilize a single TileMatrixSet. Similarly, tileMatrixSetDefinition would still point to our local definition (for consistency), the TMS definition would contain GoogleMapsCompatible WKSS, AND the tileMatrixSetURI could point to the official 2D-TMS definition. /collections/{collection_id}/tiles/{tileset_id} response would always have to define the min/max zoom/levels since they share the same TileMatrixSet.

Thoughts?

[jerstlouis]

@mcechini Option 2.

Even if different tile matrices are available for different resolution, this is definitely the same Tile Matrix Set and tileMatrixSetURI should always point to http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad. tileMatrixSetDefinition can optionally be present and point to a local definition, but on the same server for all of these cases it should always point to the same WebMercatorQuad definition with all of the levels potentially needed.

The way to identify which tileMatrices are available is through the tileMatrixSetLimits property containing only the tile matrices for which data is available. This is currently how the 'min/max' zoom levels are defined for the Tiles API using the "OGC JSON". For TileJSON, it uses minzoom/maxzoom property instead. It might be valuable to also add a min/max zoom level property for the OGC JSON one, but one issue is that tile matrices are defined as a text string in that case. Also, I have been arguing for a common scale denominator and/or resolution being defined as part of Common - Part 2: Geospatial Data.

[mcechini]

The downside I see to Option 2 for clients is that they must parse every /collections/{collection_id}/tiles/{tileset_id} (or possibly collections/{collection_id}/map/{styleId}/tiles/{tileset_id}) to determine what the min/max zoom level is for each collection's tileset. With option 1, they could short circuit that simply by recognizing the unique TMS. We have nearly hundreds and hundreds of layers in our API... which is a lot of requests to get all those collection-specific tileset resource definitions. But I suppose it's a fairly simply code loop to gather the info.

Regardless, I don't think this changes the proposal in this ticket.

[jerstlouis]

@mcechini The clients must still parse the individual tilsets to retrieve the links to tiles, unless assumptions are made about the tiles paths.
Clients may also want to parse the tile matrix sets limits, but they could deduct that from the extent.
If a max scale denominator / resolution is either agreed upon and made available, they could also potentially use that to determine the max available level.

But the canonical recommended approach for tiles access would be to fully parse the individual tilesets.

Clients would also only potentially do all this for layers being visualized. Also potentially multi-layer vector tiles tilesets might be one way to reduce the number of layers (or at least offering the option of both multi-layer and individual layers).

[joanma747]

wellKnownScaleSet is part of the tileMatrixSet definition.

About TileMatrixSetURI / Def ... we decided this: 2020-10-29

• tileMatrixSetDefinition is the one offered by the service in a different path. Required for custom TMSs and optional to point to an internal repetition of the ones present in the annexes (and in the NA).
• tieMatrixSetURI is a pointed to the NA (and the annexes). We should push for the NA to return a json representation. Required if the "standard" TMS is used.
• tileMatrixSet is not intended for OGC API Tiles.

The issue will be closed when opengeospatial/2D-Tile-Matrix-Set#11 is closed.

[joanma747]

We checked this is applied in the TMS 2D so we close it in members meeeting 2020-12-09

[tschaub]

Now I'm more confused than when I opened this ticket 😕

[jerstlouis]

@tschaub See https://github.com/opengeospatial/2D-Tile-Matrix-Set/blob/master/standard/clause_7_tilematrixset2d_model.adoc

tileMatrix‌SetURI : Reference to a tileMatrixSet -- Zero or One (optional)
b Points to a definition of the TileMatrixSet in the OGC NA (extracted from [annex_d] and [annex_h])

tileMatrix‌SetDefinition: Reference to a tileMatrixSet -- Zero or One (optional)
c Points to a definition of the TileMatrixSet provided by a tile service

d At least one of the TileMatrixSet, TileMatrixSetURI or TileMatrixSetDefinition is mandatory and shall be provided.

(The TileMatrixSet one does not apply to the Tiles API, it is for self-contained tile set definition embedding the full TMS definition).