Confusion about Recommendation 1.B and Requirement 1.A

[tschaub]

Recommendation 1.B looks like this:

A tiles implementation SHOULD consider to specify the variables {tileMatrix} even if there is only one valid value for them.

On the previous page, Requirement 1.A reads (in part):

The tiles making up a tileset containing available data SHALL be available as an HTTP GET request to a URI that can be built from a template containing three variables...

If the tileset URL is required to have three variables, is it necessary to recommend that one of those should be used (even if there is only one value). It isn't clear to me how someone would follow Requirement 1.A but not recommendation 1.B.

It looks like previously, the same recommendation included a bit about {tileMatrixSetId}: https://github.com/opengeospatial/ogcapi-tiles/blob/ba0ce15e331fe01f47f74a8bc1e0eb9d509d04bc/core/standard/recommendations/tileset/REC_tc-op.adoc#L6

The part about {tileMatrixSetId} was removed in e8ba44fbf239e30213c5b33771445036818a9a2f.

Is Recommendation 1.B meant to be about recommending the use of the optional {tileMatrixSetId} instead of {tileMatrix}?

[jerstlouis]

@tschaub

Is Recommendation 1.B meant to be about recommending the use of the optional {tileMatrixSetId} instead of {tileMatrix}?

No, {tileMatrix} is the intent here. Tile URIs cannot contain any additional variables. {tileMatrixSetId} as a templated link was removed a while back after a dedicated end-point for tileset metadata and the TileSet conformance class was added.

However, an implementation can still use a {tileMatrixSetId} within the API definition (e.g., in the OpenAPI document). An explicit permission for this is included in 7.1.5.

The Core conformance class and its requirement 1 specifies that the URI must be expressed using three variables, but does not prescribe any specific name for these variables. The recommendation 1 A is for specific names and order for them.

About recommendation 1 B, I guess the intent was that requirement 1 does not strictly require the template to use {tileMatrix} if only one tile matrix is provided, and could have been better expressed as "from a template containing at most three variables", for cases where a single tile matrix / zoom level is available.

[tschaub]

requirement 1 ... could have been better expressed as "from a template containing at most three variables"

Ah, I see. That seems like a significantly different requirement. I read the current Requirement 1 as though an implementation would be invalid if it did not have three variables. It sounds like you are saying that maybe a valid implementation could have 1 or 2 or 0 variables.

[jerstlouis]

@tschaub Yes this is a good point you raised here, we would need to decide one way or the other, either rephrasing the requirement or eliminating the redundant 1 B recommendation.

I could definitely see a use case for a single tile matrix, but a single row or column (or single tile) is not so much a 2DTMS tile API. Clients should not have difficulties with only two variables if they implement generic variable substitution, i.e. if they only substitute variables that they see in the templated URI, as opposed to expecting the presence of every one of them.

This extra flexibility would allow implementations offering a single tile matrix but not including the canonical ID of that tile matrix in the URI to conform, so I would suggest that we at least allow URIs with only row and column variables.

[jerstlouis]

SWG 2022-08-04: Early discussions suggests that it would be fine to clarify the requirement as "up to three variables" or "two or three" variables. Additional feedback welcome.

[tschaub]

My opinion is that it is a lot of extra prose that risks misinterpretation for pretty limited benefit. I think I would stick with just saying three variables are required.

[joanma747]

In the end we manage to create a long sentence describing when 2 o 3 variables are required. Allowing for 2 variables will make implementations of tiles of a single zoom level simpler.