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

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

Notes/additions/updates

• [x] add note about what "Default" means in Structure section https://github.com/mapbox/tilejson-spec/pull/37#discussion_r185637448
• [x] consistify usage of "keys" or "fields" across the spec - currently the specification uses keys
• [x] consistify references to "set of tiles" - avoid using "tileset"
• [x] "key-value" vs. "key value"
• [x] clearly define the word "implementation" (per feedback from @pnorman)
• [x] add section note about how "interactivity" for GL-based maps is not represented by the TileJSON specification, and relates to older map formats https://github.com/mapbox/tilejson-spec/pull/44#issuecomment-388977597
• [x] double check usage of "integer" and examples using "10" strings.
• [x] consistify all usages of the word "tilejson"
• [x] clarify that tile URL must be absolute per https://github.com/mapbox/tilejson-spec/issues/51
• [x] 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

• [x] attribution https://github.com/mapbox/tilejson-spec/pull/37
• [x] bounds https://github.com/mapbox/tilejson-spec/pull/39
• [x] center https://github.com/mapbox/tilejson-spec/pull/41
• [x] data https://github.com/mapbox/tilejson-spec/pull/43
• [x] description https://github.com/mapbox/tilejson-spec/pull/37
• [x] grids https://github.com/mapbox/tilejson-spec/pull/44
• [x] legend https://github.com/mapbox/tilejson-spec/pull/45
• [x] maxzoom https://github.com/mapbox/tilejson-spec/pull/38
• [x] minzoom https://github.com/mapbox/tilejson-spec/pull/38
• [x] name https://github.com/mapbox/tilejson-spec/pull/37
• [x] scheme https://github.com/mapbox/tilejson-spec/pull/38
• [x] template https://github.com/mapbox/tilejson-spec/pull/46
• [x] tilejson https://github.com/mapbox/tilejson-spec/pull/37
• [x] tiles https://github.com/mapbox/tilejson-spec/pull/40
• [x] vector_layers #42
• [x] version https://github.com/mapbox/tilejson-spec/pull/37
• [x] 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 https://github.com/mapbox/mbtiles-spec/issues/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 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.

[GretaCB]

Update

Both @mapsam and I (@gretacb) are out on vacation for the next two weeks, therefore this push will be temporarily paused until we're back. Of course comments and perspectives are absolutely welcome in the meantime, we'd love to hear your thoughts.

Super excited to come back refreshed and ready to push this through. Thanks again for everyone's patience and contributions so far, and have a wonderful couple of weeks! 👋 🏖

[mapsam]

@GretaCB let's plan on including the fillzoom property in v3 as well, since we can benefit from a single point of reference for this complicated topic. I'll make a PR into this branch so we can discuss there! https://github.com/mapbox/tilejson-spec/issues/27

[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!

[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.