version 3.0.0

[mapsam]

This is the main branch for version 3.0.0 development of the tilejson specification. Descriptions of the scope of v3 can be found in #35. All open tickets that are under discussion for v3 are labelled as v3.

Lead authors are @mapsam and @GretaCB

We'll be making separate pull requests for each field into this branch so we can keep discussions about individual properties properly located. If you have comments about the general structure of the 3.0.0 specification, feel free to leave them here!

TODO - this list will be updated as we make pull requests and merge into this branch

Overall

• reviewed Purpose section
• reviewed File format section
• reviewed Structure section
• add examples
• update schema.json
• reviewed Examples section
• order fields by REQUIRED first, then alphabetical
• add Caching section https://github.com/mapbox/tilejson-spec/tree/master/2.2.0#3-caching
• update changelog w/ new additions and breaking changes

Notes/additions/updates

• add note about what "Default" means in Structure section attribution, name, tilejson, version, description #37 (comment)
• consistify usage of "keys" or "fields" across the spec - currently the specification uses keys
• consistify references to "set of tiles" - avoid using "tileset"
• "key-value" vs. "key value"
• clearly define the word "implementation" (per feedback from @pnorman)
• add section note about how "interactivity" for GL-based maps is not represented by the TileJSON specification, and relates to older map formats grids #44 (comment)
• double check usage of "integer" and examples using "10" strings.
• consistify all usages of the word "tilejson"
• clarify that tile URL must be absolute per tiles Property should clearly highlight if relative urls are supported or not.  #51
• clarify if bounds left can equal bounds right (i.e. a single point in a tileset [0.0, 0.0, 0.0, 0.0])

Add content/review structure sections

• attribution attribution, name, tilejson, version, description #37
• bounds bounds #39
• center center #41
• data data #43
• description attribution, name, tilejson, version, description #37
• grids grids #44
• legend legend #45
• maxzoom maxzoom, minzoom, scheme #38
• minzoom maxzoom, minzoom, scheme #38
• name attribution, name, tilejson, version, description #37
• scheme maxzoom, minzoom, scheme #38
• template template #46
• tilejson attribution, name, tilejson, version, description #37
• tiles tiles #40
• vector_layers vector_layers #42
• version attribution, name, tilejson, version, description #37
• fillzoom http://github.com/mapbox/tilejson-spec/pull/50

Post release TODO

• open v4 ticket suggesting renaming vector_layers.id -> vector_layers.name
• revisit update to MBTiles specification Update vector_layers to match tilejson-spec 3.0  mbtiles-spec#53
• open ticket about combining tilestats & tilejson into the same specification
• open ticket about removing grids and interactivity fields from the specification - or generally open ticket about removing UTF-grid and interactivity fields like legend and template
• open ticket about top-level field describing vector or raster, which helps consumers determine whether vector_layers is required or not.

cc @mapbox/core-tech

[mapsam]

@GretaCB Since vector_layers is the first field with two words, do we want to explicitly document that we prefer underscores _ as separators?

[mapsam]

@GretaCB do you have an idea of what order we should put the fields in the Structure section in? Right now they are listed alphabetically, but they could also go in order of "REQUIRED" first and "OPTIONAL" second, or something else entirely.

cc @flippmoke who may have some thoughts here

[flippmoke]

@mapsam I think required first might be best, but alphabetical works as well. I would just make sure its quickly clear what is required somehow so that it can be "checked" off if you were reading the spec and implementing it.

[GretaCB]

"REQUIRED" first and "OPTIONAL" second

👍 agreed, and alphabetical within those sections?

[mapsam]

and alphabetical within those sections?

Sounds good! Thanks both of ya 🙏 Let's plan on re-ordering at the end so we can focus on writing now. Will add as a checkbox before we merge.

[pnorman]

• It's not clear what an implementation is or does.

• Content reviewed didn't include center, data, grids, legend, template, or vector_layers

[pnorman]

This is requiring implementations to have an API

[GretaCB]

Great point. What are your thoughts on a more generic description?

“… implementations MUST expose unknown key/values so users can optionally handle these keys.”

cc @mapsam

[pnorman]

Take an example implementation stitches tiles into an image based on a tilejson (and bounding box, scale, zoom). It might not expose any key/values, including known ones, so could never be compliant.

[GretaCB]

@pnorman I added the above quote to this PR based on your initial comment. Please provide example wording if you’d like further edits.

[pnorman]

Allowing HTML or literal text without saying how to pick which it is interpreted as is ambiguous.

[GretaCB]

Agree that this is unclear, since the goal of v3 is to document current usage and implementations are currently deciding between HTML and plain text, there isn’t much room for extra clarification. Let’s plan on addressing this by updating this field entirely in v4, for example #20.

[pnorman]

This is inconsistent with the xyz naming schema for tiles or tms with global mercator.

[GretaCB]

Trying to clarify, are you referring to these coordinates…

    [ -180, -85.05112877980659, 180, 85.0511287798066 ]

and that they should be the default to avoid going beyond xyz-compliant tile bounds?

cc @mapsam

[GretaCB]

Updated to this PR.

[mapsam]

Update: Carol and I have added all planned updates and changes based on external and internal input. Next steps are to get more eyes and reviews on the final draft. Tagging @samanpwbb @ian29 @alliecrevier @flippmoke @stevage for starters, please feel free to review if you have time (but no pressure if you don't)!

Our plan is to have this merged into master next week.

[mapsam]

Also cc @andrewharvey if you'd like to give this a review!

[samanpwbb]

is it worth mentioning overzooming in this description?

[mapsam]

@samanpwbb what context do you think we should mention this? Similar to fillzoom above, I'm having a hard time determining how prescriptive or descriptive to be when it comes to how servers should act. I don't want to force tile servers to do anything they don't want to, but we can definitely provide some extra context/clarity for complex topics like overzooming. What about a descriptive helper sentence like:

Overzooming (link to a definition somewhere?) support is implemented by clients or servers. The specification does not enforce whether overzooming is available or not, merely provides information so servers and clients may better generate overzoomed tiles.

This feels like a statement that could exist outside fo the maxzoom field, too.

[samanpwbb]

After thinking about this more (from prompt by @stevage), what I'd really like to see is an explicit description somewhere in tileJSON about the server-side over and under-zoom range (see #36 (comment)).

This matters because often client applications (like Studio) are responsible for communicating to users who may not understand how tiles work why their data layers are or are not visible on the map at any given time.

[mapsam]

Interesting @samanpwbb - so you're thinking something like an overzoom property? Like:

{
  "minzoom": 0,
  "maxzoom": 15,
  "fillzoom": 8,
  "overzoom": 30
}

And this way the client knows it can safely make requests beyond the maxzoom (where data is available) but expect anything greater than maxzoom to be overzoomed.

Would you mind opening a ticket to discuss for v4?

[lukasmartinelli]

Why is this not merged?! @mapsam

[stevage]

Has this been officially abandoned?

[dqunbp]

Is it officially abandoned?

[mapsam]

Thank you all for the reviews and feedback!

This was abandoned a couple years back due to a shift in work priorities. Apologies for not being clear about this. I've spent some time cleaning up the PR and think this is ready to be merged. For transparency, please note that the api.mapbox.com servers have not been updated to reflect "tilejson": "3.0.0" at this time.