Out of bounds and empty tiles consideration (204, 404, 400; Full & Empty tiles)

[jerstlouis]

1. In VTP2, in order to populate a GeoPackage a client requests tiles and does not necessarily inspect the content. Since some tiles media types cannot be 0 bypes, potentially the client could not know whether the tile is empty (although Mapbox vector tiles can be 0 bytes).

The recommendation would be that a 204 return code could optionally be returned by the server, assuming the requested tile was within the TileMatrixLimits. This would allow 0 bytes responses for media types which cannot be 0 bytes. There are some arguments about whether that is proper or not for a GET request, but the HTTP specification does say that is valid, but there must not be any content returned.

2. When a requested tile falls outside the TileMatrixLimit, but within the overall global TileMatrixSet definition, a 404 should be returned (this should be in line with current draft specs).

3. However if the tile falls outside of the global TileMatrixSet definition altogether, a recommendation is that a 400 would be more appropriate (this may not be reflected right now in the draft specs).

4. Also, a suggestion for two optional tile statuses, which could be included as a response header:

• 'Empty all the way zoomed in' -- for large areas where there is absolutely no data at any zoom level even further down, but within the TileMatrixLimit. This would avoid having to request the levels further down and save tons of requests.
• 'Completely full tile' -- for large polygons with detailed contours, e.g. lands and oceans as filled polygons. This would avoid having to request the levels further down and save tons of requests.

[cportele]

Potential reasons for not returning a 204:

• If the server is streaming the response, it will typically start the response at a point when it is unknown, if the response will contain, for example, any features or not. I.e., supporting the 204 approach would have a negative impact on the performance for fetching tiles that are not empty, at least in the cases where tiles are constructed dynamically.
• Returning yet another status code requires special handling in clients.
• Yes, a 204 response to a GET request is valid HTTP, but client developers may still find using 204 for a GET request unusual. It is mostly used as a response for PUT or DELETE requests to indicate that the client does not need to change its context to the URI of the request. There should be sufficient feedback from client implementations that they think that 204 is a good idea to recommend this approach.
• A 204 is probably the equivalent to a null/nil value without any content type, which is different from an empty set in a content type. Related to this is also that the behaviour would differ from the behaviour of other resources, e.g. the Features resource (/collections/{collectionId}/items).

[pomakis]

I think that even if the requested tile falls outside of the global TileMatrixSet definition altogether, a 404 response would be better.

It's more compatible with lazy clients that might not bother clipping tile requests to the TileMatrixSet bounds, and is also easier for servers, since its potentially one less thing for them to check during the processing of a tile request. It allow keeps the possibility open for file-system-only tile servers. I think it's conceptually better, too.

I think each of these requests should result in a 404:

/collections/myCollection/map/myStyle/tiles/dfndffgh
/collections/myCollection/map/myStyle/tiles/3/654673723/5
/collections/myCollection/map/myStyle/tiles/3/dfghgh/5
/collections/myCollection/map/myStyle/tiles/3/6

(Where /collections/myCollection/map/myStyle/tiles/3/6/5 would result in a 200.)

In general, if the path doesn't point to a resource, it should be a 404.

[pomakis]

I like the idea of an optional 'Empty all the way zoomed in' hint in the response header. I'm not as sure of the value of a 'Completely full tile' hint though, since its usefulness would be limited to blandly-styled polygon-based layers.

[jerstlouis]

@pomakis in fact I think the completely full is more useful than the completely empty.
Why do you say its usefulness is limited to blandly-styled? This is for any vast polygon which can have a very detailed edge but will have large "full areas" (e.g. the whole landmass of the Earth at high resolution).

[pomakis]

These hints were proposed as a way to "avoid having to request the levels further down and save tons of requests". For map tiles, a completely empty tile is simply a fully-transparent tile (or possibly a solid tile in the style's background color). Such tiles can exist in any mappable data set (including coverage data sets that aren't a complete coverage of the world), and there are usually quite a lot of them.

But a "completely full" tile? What does that even mean? It's mostly meaningless for coverage layers, and for layers that render points or line data. An inner tile of a filled polygon can be said to be "completely full", sure, but full of what? Only if the polygon fill is a solid (i.e., "bland") color would this flag be of any use. Because if there's any color gradient or fill pattern, the higher-zoom-level tiles will be different.

That's why I think a 'Completely full tile' hint would have far less utility than an 'Empty all the way zoomed in' hint.

[jerstlouis]

@pomakis I am referring specifically to polygon vector tiles.
It is more of a tiled vector data storage problem, but if one populates e.g. a GeoPackage from a Tiles API, there needs to be a mechanism to convey the fact that this tile is a completely full polygon.
Styling consideration are irrelevant here because I am talking about retrieving the 'data' tiles.

But yes I realize there could be other uses for this with coverage and map tiles as you point out, which in that case would possibly benefit more from marking "empty" -- but what you call a full solid color, as opposed to transparent, would be the "full" equivalent to me in raster, but I believe the greatest value for this is the inside of polygons (as has been shown many times with OpenStreetMap where special background tricks must be used to render land or ocean). But this would provide a clean and elegant approach to storing vast polygon vector tiles.

[ghobona]

We still do not have a solution to the problem identified by Item 1 from #21 (comment). If 204 is not appropriate, please suggest an alternative.

Item 2 from #21 (comment) is already covered by Clause 7 (through a 404 code).

I think we can update the section with Item 3 from #21 (comment). Any objection?

[joanma747]

There are 2 places were they generated tiles and return 204:
CesiumGS/cesium#7936
mapbox/mapbox-gl-js#9304
The coverages API currently proposes to use 204.

The https://tools.ietf.org/html/rfc7231#section-6.3.5 seems to suggest the convenience to use this in PUT but does not prevent to use it in GET

We tested chrome and firefox and force them to manage a 204 with: https://httpstat.us/204 and they react by defaulting to the previous page (in contrast to 404 that remains in the page showing the message (and the reason?)

In 2020-11-05 telco we decided this:

• For a tile outside the tilematrixset or tilematrixsetlimits we will return a 404 (the 400 possibility was considered not necessary).
• For a tile with content 200 will be returned
• For an empty tile (e.g. a transparent image or a void vector tile) we allow two options
  ** 200 with a file with nothing "visible" (e.g. an empty file or a PNG with internal headers and no "pixels", ...)
  ** 204 (No content) with no HTTP body at all.

[jerstlouis]

The remaining part of the recommendation we did not address today concerns large polygon datasets where the vast majority of the tiles are either empty or full (e.g. the global landmass).

The suggestion is that something in the response header could indicate that there is no point in requesting tiles at deeper zoom levels, because you will get back either a full (completely inside the polygons) or empty (completely outside the polygons) resonse. Similar capability would be needed as well for storing this information, and this would result in very substantial bandwidth/storage savings (probably something like 95% savings with a polygons dataset generated from OpenStreetMap natural=coastline).

Regarding empty, when getting a an empty response at say level 5, it can either mean that there's is nothing at this level because any features present are too small to be seen at this zoom level, or it could mean that there really is nothing within this tile extent at all in this dataset at any zoom level (the latter case is what the client could be informed of with a particular response header).

[joanma747]

Last comment does not modify the resolution.

[jerstlouis]

Filed the second part about indicating whether tiles are empty/full all the way down as separate issue #63 .

[joanma747]

Since the second part is now a separate issue and the first part has been addressed in the document, I'll close this issue.