Revamp Plan: v3 and v4

[GretaCB]

👋 We are ramping up efforts to document the current spec as well as discuss a future version with all contributors. This ticket serves as the overarching plan forward. @mapsam and I are excited to be leading out this process and collaborating with you all.

What’s been happening?

No doubt there is a need to have a clear set of tileset metadata in order to support interoperability between different tile-based geo tools. This is the need TileJSON aims to fill. However, the TileJSON spec has not been consistently maintained for a number of years due to original owners moving on to other projects or organizations, which has led to inconsistencies. @mapsam and I are picking up the torch to address this.

We are committed to ensuring the current spec as well as future spec additions are properly documented and all changes fully transparent. To achieve this, all proposed changes will follow TileJSON spec’s contributing procedures. @mapsam and I are also committed to shepherding TileJSON spec’s Code of Conduct during this ramp up. Please reach out to either of us if you have any questions about these docs.

Phase 1

v3.0

Goal: Solidify our understanding of the current spec, documenting, then release v3.0. This will enable us all to discuss and implement our visions for how we want things to be in Phase 2 (see below).

Phase 1 will center around fully documenting the already-existing spec as well as any relevant historical context. We are prioritizing this due to there being an ownership gap and a general lack of clarity in the past around fast changes and maintenance of the spec. We’ll plan to create PRs for each of the next actions below, where we will continue discussion for each.

We are aiming to finish Phase 1 by May 2018.

Next Actions

• Add undocumented properties and expand on documented properties as needed
• Respond to all existing issues regarding Phase 1, adding historical context as needed
• Reformat and improve searchability of README
• Ensure consistency with RFC 2119
• Include concrete examples for every field
• Create Milestone for easy tracking

Phase 2

v4.0

Goal: Discuss modifying current properties and adding new features, then release v4.0

Next Actions

• Respond to all existing Issues proposing new additions, changes, or removals
• Consider how v4.0 is impacted by the upcoming Vector Tile 3 spec
• Create Milestone for easy tracking

Thanks for your continued commitment! 🙌

cc @mapbox/core-tech

[mapsam]

The 3.0 branch has been created - we'll be using this as the main spot for discussion: https://github.com/mapbox/tilejson-spec/pull/36

[tomass]

Where should we add suggestions?

I would like to suggest adding a list of available fonts for a glyph url, which currently looks like this: "glyphs": "https://myserver.com/font-glyphs/{fontstack}/{range}.pbf",

I suggest something similar to what vector_tiles source has - url to the json file with source properties as well as list of vector layers. Link to glyphs could also link to json with a list of available fonts.

[kkaefer]

@tomass This proposal sounds like it's outside the scope of TileJSON. As the name suggests, this spec describes tilesets only and doesn't have a notion of other entities of the GL stack (TileJSON even predates GL).

[tomass]

@kkaefer should I put this proposal somewhere else or it simply does not have a place (is irrelevant)?

[kkaefer]

Glyph URLs don't have a specification. The Mapbox API allows retrieving the fonts available at an end point, but it's not available as a public API and requires a token with the appropriate permissions. If you run your own glyph server, you can implement this API yourself, but there's no convention for it, and Mapbox GL does not ever request it.

[tomass]

@kkaefer OK, thank you.

[pnorman]

What are the governance plans for the specification?

[pnorman]

What are the governance plans for the specification?

For background, the general requirement for an open standard would be a mix of users and implementers, implementers not dominated by one area of implementation at the cost of others, and not dominated by any one organization. This makes sure that an open spec represents everyone's interests, not just one companies.

[mapsam]

Hey @pnorman, as stated above, myself (@mapsam) and @gretacb will be the lead authors and deciding committee of these two versions. We are following the CONTRIBUTING.md, which states all questions and suggestions should be opened up as GitHub issues. Thanks for the input so far!