TileJSON doesn't seem to support Mapbox's own vector tiles spec. Am I misunderstanding something, or is this an omission?

I can see two ways to support it:

1. The data element should allow URLs that end in .pbf and return PBF files. But then, with the REQUIRED tiles attribute, it would be a bit awkward to conform to the spec for a purely vector source...
2. The tiles element should allow URLs that end in .pbf and return PBF files.

Either way I guess the scope of the spec is changing, since presumably it was originally envisaged that this was strictly for raster tiles and here it is being used for vector data...

Pending a spec for the format of the geocoder result JSON and implementation in MapBox API.

The spec does not currently support any way to describe the layers contained within the tiles. This means that the client has to "somehow know" which layers exist. IMHO this kind of metadata makes a lot of sense to include.

Both Mapbox's API and the tile server Tessera uses the "vector_layers" property for this purpose:

    "vector_layers": [
        {
            "id": "tr_rail",
            "description": "",
            "minzoom": 0,
            "maxzoom": 13,
            "fields": {
                "FTYPE_CODE": "String",
                "NAME": "String",
                "STRUC_TYPE": "String",
                "TOUR_TYPE": "String"
            }
        }
    ]

Mapbox's API includes source and source_name properties on individual layers. (The former for the case where a multiple sources are being combined in one query, I presume).

I'm happy to write this up as a PR if desirable.

Add "crs" (= Coordinate Reference System) as key.
The values and if it should be mandatory has to be discussed.
See also e.g. https://github.com/klokantech/tilejson-spec/tree/custom-projection/2.2.0

Some tile server implementations support overzooming, where tiles are generated and served at zoom levels beyond a tileset's zoom extent using the lowest available zoom level as the source of truth for overzoomed tiles.

Mapbox's tile server includes an overzoom max of 30 for all vector tilesets, which means tiles can be requested from any tileset from the minzoom to zoom 30, regardless of the maxzoom. Requesting tiles beyond z30 from Mapbox results in a 422 error.

If overzoom were a property on tileJSON, clients would know when to stop requesting tiles without hitting an error or relying on a separate source of truth.

I'm pretty sure that there are TileJSON files - as well as services and data - around which contain maskLevel.
The logic is described here: https://github.com/mapbox/tilelive-vector
Should'nt this be part of the spec.?

Mapbox iOS SDK hints that it may be possible to customize the batch sizing of tile packs. I would like to create a batch for 11-12 since I don't need >=13 and it's throwing me over the 750 limit.

The zoom leveling scheme for the tile batches can be defined in Tile JSON, otherwise the default scheme is used...

@property (nonatomic, readonly, nonnull, copy) NSString *styleURI;

/**
 * Minimum zoom level for the tile package.
 *
 * Note: the implementation loads and stores the loaded tiles
 * in batches, each batch has a pre-defined zoom range and it contains
 * all child tiles within the range. The zoom leveling scheme for the tile
 * batches can be defined in Tile JSON, otherwise the default scheme is used:
 * - Global coverage: 0 - 5
 * - Regional information: 6 - 10
 * - Local information: 11 - 14
 * - Streets detail: 15 - 16
 *
 * Internally, the implementation maps the given tile pack zoom range
 * and geometry to a set of pre-defined batches to load, therefore
 * it is highly recommended to choose the `minZoom` and `maxZoom` values
 * in accordance with the tile batches zoom ranges (see the list above).
 */

Some renderers (like ours) require to map a geometry type to a layer. Therefore I propose to have an optional field "geometry_type" for the layer definition. The geometry_type should relate to one of the simple feature types of defined in GeoJson [1]:

... geometry type refers to seven case-sensitive strings: "Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon", and "GeometryCollection"

[1] https://tools.ietf.org/html/rfc7946#section-1.4

Similar to center it would specify an extent that could be used to to set the default center and zoom. Extent would allow a specified area to always be shown, no matter the map size.

If "bounds" is missing, how do I know valid tile-x/y? If the center is also missing, I don't see any possibility to even get valid tile-xy. This problem would be solved by making the "bounds" key required instead of optional.

👋 Plan is to start ramping up efforts to update and document this spec. This repo is missing needed documentation for moving forward, in particular Contributing.md and Code_of_Conduct.md, which I will break out into separate PRs.

An entire tileset has min/maxzoom, but individual layers in a vector tileset may have different min/maxzooms within the tileset's range. It can be helpful for downstream consumers of the tilejson to know where these layers are visible.

cc @samanpwbb

.layer is a silly name.

It appears that the tiles property is not clear enough regarding the support of relative and absolute URLs.
I lately opened a issue on mapbox-gl-js that relative URLs are not correctly handled but the bug was closed with the info that absolute URLs are needed in the tiles property. From the current description it is not 100% clear that his is actually a requirement:

It appears that some services like ESRI ArcGIS only specify relative URLs which need to be combined with the URL where the TileJSON is hosted.

Either the spec should mention that only absolute endpoints are supported or it should clearly define how relative URLs should be handled, especially in regards to leading slashes.

As explained in mapbox/mapbox-gl-native#2723 (comment), native map controls need attribution information in a format other than HTML source code. We should allow the attribution property to be set to something more structured that can be converted to the appropriate data structures on the client side. For example, it could be an array of objects, each with a required title property (interpreted as literal text) and an optional url property (for linking):

{
  "attribution": [
    {
      "title": "© OpenStreetMap contributors",
      "url": "http://www.openstreetmap.org/about/"
    },
    {
      "title": "Creative Commons Attribution-ShareAlike 2.0",
      "url": "http://www.openstreetmap.org/copyright/"
    }
  ]
}

Other considerations:

• Should the title property be localizable? If so, perhaps it should be set to an object mapping ISO 639 language codes to literal strings.
• Mobile clients are often space-constrained. In the example above, it may be advantageous to abbreviate the two items as “© OSM” and “CC BY-SA”. These abbreviations could go in a short_title property beside the title property.
• Should other formatting be allowed? The current specification doesn’t disallow any HTML tags, so it’s theoretically possible to boldface text or embed images. While such content may be feasible in Web clients, native clients may have difficulty displaying it.
• Perhaps there should be a separate feedback property beside the attribution property. Many TileJSON documents hosted by Mapbox include an “Improve This Map” link alongside copyright statements. Native clients may want to open an alternative map feedback tool (mapbox/mapbox-gl-native#6001); as things stand, they’d have to look for and omit a specific URL. In space-constrained environments, the client may choose to omit feedback items from the attribution UI to ensure that all the legally required copyright statements are visible.

/cc @kkaefer @jfirebaugh

Is there a reason why the tiles and grids urls use a ${z} style token for replacement?

Out of the box, it looks like modest maps uses {Z} while leaflet uses {z}.

• https://github.com/stamen/modestmaps-js/wiki
• http://leaflet.cloudmade.com/examples/quick-start.html

Wondering if we should switch and maybe come to a consensus on the right token to use.

/cc @kkaefer @tmcw

For the case where these values aren't tiled/templated, it would be nice to be able to inline the JSON and reduce server round-trips.

Motivation

I've come across a lot of different tile layer sources over the years which tend to have multiple areas of coverage (multiple bounding boxes). A great example of this would be a high resolution imagery layer that only focuses on urban areas. Currently to limit the tile requests to these areas we have to create a layer number of tile layers, one for each bounding box.

Design

It would be great if we could specify multiple bounding boxes in a single layer, or possibly a MultiPolygon instead. Not sure of how else to handle this. One potential issue with this approach is that processing time of determining if a tile is within the coverage area or not. To improve performance this could be pre-calculated when the tile layer is initially loaded and an index created based on the tile ids. Limiting this to bounding boxes, would simplify things and may be good enough for most scenarios like this.

Mock-Up

For a developer, they would simply pass in an array of bounding boxes as an alternative to passing in one.

Concepts

This isn't much of a change from the API interface point of view, so not much to new learning required. This would also be beneficial to those who use OGC services that have complex coverage areas.

TileJSON should have a means of:

• indicating when a source supports high-DPI versions of base tiles, and at what DPI multipliers (@2x, @4x, etc)
• specifying how URLs for high-DPI tiles are constructed

Without such a specification, consumers must have hard-coded knowledge of a source's support for high-DPI tiles and typically resort to string munging to generate the appropriate URLs. These are exactly the sort of deficiencies that TileJSON is designed to eliminate.

One approach would be to have an array-valued property that lists supported DPI multipliers and a new interpolation key for tile URL templates. E.g.:

{
  ...
  "dpis": [1, 2, 4],
  "tiles": ["http://example.com/{z}/{x}/{y}{r}.png"]
}

Where it is specified that {r} is replaced with the pixel ratio ⇢ string mapping of 1 ⇢ "", 2 ⇢ "@2x", 4 ⇢ "@4x", and consumers may decide which of the pixel ratio options to use based on device characteristics. Alternatively this mapping could be explicitly supplied:

{
  ...
  "dpis": {
    "1": "",
    "2": "@2x",
    "4": "@4x"
  },
  "tiles": ["http://example.com/{z}/{x}/{y}{r}.png"]
}

These approaches introduce a backward compatibility issue however, in that existing TileJSON consumers will not be prepared to interpolate a new template value and thus cannot consume TileJSON that uses it.

cc @yhahn @mourner @tmcw

Landing on the repository one can see all spec versions up to 2.2
There is a branch with a v3 that is not visible unless one knows where to look.
Wondering what's the situation, one can imagine that maybe:

• v3 was never completed and did not get merged
• v3 is not merged into master due to a simple oversight
• the is just a different convention in managing the branches

What do people think about adding an interpretation field for raster sources?

Currently Mapbox use TileJSON for

1. a 3 band RGB raster to be displayed as is https://api.mapbox.com/v4/mapbox.satellite.json

2. a 1 band raster encoded as a 3 band RGB.
   https://api.mapbox.com/v4/mapbox.terrain-rgb.json (https://blog.mapbox.com/blog/terrain-rgb/)

In the terrain-rgb case the formula for getting back to the 1 band raster is "-10000 + ((R * 256 * 256 + G * 256 + B) * 0.1)".

Should the TileJSON spec distinguise these two types and contain the formula to get the real values like in (2)?

/cc @MateoV

Currently, all that the specification has to say about the x, y and z URL parameters is

{z}, {x} and {y}, if present, are replaced with the corresponding integers

There is no specification of what corresponding means. The specification should probably either explicitly define how x, y and z are calculated from geographical coordinates, or link to another standard that specifies it.

The current text of 3.0.0 has a couple of problems for raster layers

Note: When describinng a set of raster tiles or other tile format that does not have a "layers" concept (i.e. "format": "jpeg"), the vector_layers key is not required.

There's a few issues that should be changed for 3.0.1

1. Typo in "describinng"
2. use of "i.e." In a case where there is an example, it should be e.g., not i.e., as the latter says jpeg is the only raster tile format
3. Referencing format. Previous versions of the spec had a format key, but that is no longer defined in the spec, so it's unclear to users what "format": "jpeg" means
4. Making it optional. The text earlier in the section says vector_layers is required, but this changes that. Instead of sorting that out, I recommend making it optional. For vector tiles with a layer concept, it's not always necessary to know what all the layers are in order to make use of the tiles.

Opening from #35 (comment)

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.

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!

I'd like to see an open committee to make the standards process openly owned by the community, with a balance of interests. A diverse committee is generally believed to lead to better specifications.

The property would be a suggested background color for the map div.

Setting the background color to a common map color seems to reduce the effect of background flashing when tiles are getting loaded. For mapbox streets this would be the main land color

This seems like it might be going beyond the scope of tilejson-spec though?

When more than one tileset is composited, vector_layers get merged into a single list. source and source_name fields are useful for identifying which vector_layers belong to which member of a composite source.

// An example vector layer entry with `source` and `source_name`:
{
  description: string,
  fields: { [string]: string },
  id: string,
  maxzoom?: number,
  minzoom?: number,
  source: string, // Matches id of parent tileset
  source_name?: string // Matches name of parent tileset
}

This does bring up a bigger question for me. I find the tileJSON spec's ability to successfully describe composited tileJSON to be lacking. I want to know more details about each tileset in my composite. A nested data structure for composited tileJSON that includes the full original tileJSON for each composited tileset would be a much more convenient document to work with, for example.

The spec says {x|y|z}, without the $.

If I have a tile source that goes from west of Australia to east right of New Zealand, I would expect to be able to write the bounds as:

[90, -70, -170, 70] // left, bottom, right, top

Unfortunately this doesn't seem to produce a valid tilejson (in Mapbox GL JS no tiles are requested for this source).

It's not possible to workaround this by just switching the left/right longitudes, because that represents all the negative space where there is no data. Leaving the only possible workaround to specify the entire -180°/180° range:

[-180, -70, 180, 70],

This results in a lot of unnecessary requests to the server that just result in 404 responses, and also prevents the ability to draw a border around the bounds. However it works from a user perspective because all data is shown.

Extending the bounds beyond 180° to 190° (below) results in appropriate requests, but nothing between 180° and 190°(with Mapbox GL JS as the implementation).

[90, -70, 190, 70]

Should the spec be able to support bounds where the left longitude is greater than the right longitude?

The vector_layers field references format field, but it is not declared in the spec. https://github.com/mapbox/tilejson-spec/tree/master/3.0.0#33-vector_layers

Note: When describinng a set of raster tiles or other tile format that does not have a "layers" concept (i.e. "format": "jpeg"), the vector_layers key is not required.

👋 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

I understand that this use case is likely not covered by the current specification, but I wanted to document the need, and also see what contributors here recommend for satisfying the requirements as closely to the specification as possible.

I have raster imagery for a city that is relatively high resolution that needs to be tiled and displayed at the full source resolution at maximum zoom. Naturally the meters per pixel resolution of my source imagery does not align with the meters per pixel resolution of an integer zoom level at the latitude for the map.

To display imagery at its full source resolution I need to use a fractional zoom level that aligns the meters per pixel resolution of the map with the source imagery's meters per pixel resolution. Ideally the source imagery is tiled at the same fractional zoom level and then served to the client when at that maximum fractional zoom.

My current thought is to tile the imagery at the appropriate fractional zoom (to preserve resolution) as well as for each integer zoom below that fractional zoom. Let mapbox tile the imagery at all zoom levels other than maximum and when at maximum zoom have application code request and overlay the fractional zoom tiles manually. Not pretty but it would satisfy the requirements.

Do contributors here have any recommendations for how to go about this? Or potential alternatives? Any chance a future version of the specification would handle fractional zoom tiles?

For data-centric layers (e.g. dynamically updated layers containing lots of additional info for features) it will be useful to allow a wildcard definition for the layer fields:

"fields": {
        "*": "All attributes"
      }

This let's an application know that there are various attributes available, without being limited to a predefined set.

We're starting to see a lot of tilejson with a vector_layers key. We should document this for standardization and so that the meaning the keys are documented.

Some examples

https://gist.github.com/springmeyer/bbf49c89180485f477b9
https://github.com/mapbox/mapbox-studio/blob/mb-pages/test/fixtures-mapboxapi/mapbox.mapbox-streets-v5.json

Edit: fixed link

I have just been working with some Esri vector tiles, which support a variable zoom depth. That is, tiles are generated to higher zoom levels in areas that contain more detail, and aren't generated in comparatively empty areas.

https://developers.arcgis.com/rest/services-reference/vector-tilemap.htm

It has obvious benefits when statically generating large tilesets that cover both urban and rural areas. The downside is that you also need to communicate to the client where tiles are available. Esri does this through a hefty tilemap JSON file, but there probably more efficient ways.

Is it worth putting something like this in TileJSON? Or maybe it doesn't make sense if Mapbox isn't going to support it.

In https://github.com/mapbox/tilejson-spec/blob/master/3.0.0/example/osm.json, it could be interesting to set a date as optional.

Why this request?

Knowing when the vector tiles have been updated.

Limitations:

It will work better with vector tiles served from static source like an mbtile.

Otherwise, it's not always relevant if tilejson possible date is not synced with vector tiles due to dynamic vector tiles endpoint.

Maybe It's already solved if considering I optional key management as it seems from https://github.com/mapbox/tilejson-spec/blob/master/3.0.0/example/osm.json#L17 and excerpt from the spec below

Implementations MUST treat unknown keys as if they weren't present. However, implementations MUST expose unknown key value pairs so users can optionally handle these keys. Implementations MUST treat invalid values for keys as if they weren’t present.

@tmcw pointed out that we need a way to know which version of the spec is implemented. We basically need a key for this.

api ? tilejson ?

I recently added subdomain support to leaflet-tilejson (kartena/leaflet-tilejson#10) for subdomains, as it is hard to implement subdomains with TileJSON in Leaflet. I would like to recommend officially adding {s} as a valid variable in tiles, and an associated subdomains property, which can be provided as an Array or a string, just like Leaflet supports.

It would be useful to be able to have tileSize as a TileJSON property to make it easier to use non-default sized raster tiles.

Most web tiling toolkits use ${z}/${x}/${y}.png.