The Mapbox Vector Tile Specification recently graduated to version 2.0 and along with it a number of our tools and products, including some new documentation. The specification is an important way for us to encode and decode geometry within our tools to render your data as fast as possible.

What changed between 1.0 and 2.0?

The specification is much more explicit in all aspects. The number of organizations that are using and creating vector tiles continues to grow, and a more explicit standard will help to guarantee the interoperability of Mapbox Vector Tiles. If vector tiles can be more specific about the data they contain, we can speed up our tools and your maps. We can even improve the efficiency of our triangulation libraries, such as Earcut.

Previous versions of vector tiles didn’t require valid geometries (according to OGC validation), which led to rendering bugs with GL technologies, related to the triangulation libraries. Valid geometries provide better results from the use of analysis tools on the data the vector tiles contain.

ogc validity

A) This polygon has intersecting geometries, which makes it invalid. B) To make it valid, we can turn the inner loop into an inner ring with reversed winding order and, C) it will render properly with a "hole".

Some key changes in the specification include:

  • Formally clarify the intent of the specification, requiring a version field in all layers.
  • Define interior and exterior rings - knowing the winding order of polygons is important to know if they have “holes” or if they are separate features. This allows us to effectively extract data from vector tiles and safely render interior and exterior rings.
  • Clearer definitions of fields, their properties, and what they can and cannot contain.
  • Explanations of encoding commands, which are used to draw geometry on a vector tile coordinate plane.
  • File extension changed to .mvt from .vector.pbf for clarity.

What tools have changed?

If you are uploading custom data through Mapbox Studio or generating tilesets with Mapbox Studio Classic, your tilesets will be version 2.0 compliant. Version 2.0 vector tiles are backward-compatible. Anywhere a version 1.0 tile can be used, a version 2.0 tile can be substituted. Existing versions of libraries such as Mapbox GL JS and Mapbox.js work great with new vector tiles.

If you work with tools that we actively develop, such as Mapnik Vector Tile or Node Mapnik, they are now generating version 2.0 tiles. Over the next few months, we are going to explore incorporating the new specification into other, non-Mapnik tools such as GeoJSON VT and Tippecanoe.

Check out the new Vector Tiles Specification guide to learn more about vector tiles through interactive examples. And if you’re attending FOSS4GNA next month in Raleigh, hear me talk more on Mapbox Vector Tile Specification 2.0 at my session.