The Mapbox Vector Tile specification and the version number in every layer

This repository is a document, not a dependency

The project description is one sentence. It is a specification for encoding tiled vector data.

That determines everything about the repository. There is no package to install, no build step, no API. The top level holds a `README.md`, a `LICENSE`, a `CHANGELOG.md`, `CONTRIBUTING.md`, a `CODEOWNERS` file, a `CODE_OF_CONDUCT.md`, and four directories named after the versions of the specification: `1.0.0/`, `1.0.1/`, `2.0/` and `2.1/`. The published specification lives at mapbox.com/vector-tiles/specification.

The reason there is a separate directory per version rather than one moving document is versioning, and the versioning rule is stated precisely. The specification is versioned on `major.minor` notation. The `major` version is incremented with any technical change to the specification format or the way it should be interpreted, and changes to the `minor` version are reserved for any clarification or correction of clerical errors associated with the specification language.

So a major bump means the format changed and a consumer has to do something about it, and a minor bump means someone fixed a typo. That is a stricter rule than most specifications use, and it is what makes a version directory per release sensible.

The audience is therefore an implementer. Someone writing a decoder, someone writing an encoder, and someone choosing a format for a map product and needing to know what they are signing up for.

The major version travels inside the data

The detail that makes the whole scheme work is in the versioning section, and it is short.

The `major` version in the specification name is synonymous with the `version` field in a Mapbox Vector Tile layer. The documentation points at the Layers section of the 2.1 specification for the details of that field.

This is the part worth thinking about before you build on the format. A tile layer carries its own version number, so a decoder reading a layer knows which version of the format the data claims to be in, without needing to be told out of band. The specification name and the data agree because they are the same number.

That design has consequences for the whole ecosystem. A decoder that only understands 2.x can look at a 3 layer and refuse it, or a 1 layer and handle it with the older rules, and the two implementations do not have to agree on anything else. It also means the version is a compatibility statement about the data rather than about the document that describes it, which is the useful kind of version.

The layers section is where the format's own structure is defined, and it is the part of the specification an implementer spends the most time with. The repository also maintains a list of implementations at mapbox/awesome-vector-tiles, which is the fastest way to find an existing encoder or decoder rather than writing one.

Version 2.0 was a clarification, not a redesign

The version history in the README is short and tells you what kind of project this is.

Version 1.0.0 was the first release, on April 13, 2014. Version 1.0.1 followed on July 28, 2014 and its stated change was to update the `.proto` file to match the Protocol Buffer style guide and to change the namespace. Version 2.0 came on December 4, 2015, and version 2.1 on January 19, 2016, the latter described as a correction to the wording in a few locations of the 2.0 specification.

The description of what 2.0 actually did is the interesting part. The focus of version 2.0 is the clarification of the intent of the initial version of the specification, and the definition of interior and exterior rings within polygons. The fields within the protobuf are more clearly defined in this version, and the steps for decoders and encoders are more explicitly declared.

Read that as a whole and the pattern is clear. The format itself did not change, the text got more precise about what it had always meant, and the areas that needed the most work were the geometric ones. Rings, and the difference between an interior and an exterior one, are exactly where a specification is easiest to get wrong and hardest to debug from the output.

The 1.0.1 release is worth a second look for the same reason. A namespace change and a style guide alignment are not format changes, and they were shipped as a patch version, which is consistent with the rule that minor versions are for clerical corrections. The `.proto` file is the schema, so aligning it with the upstream style guide is a housekeeping change to the description of the data, not to the data.

The last push to the repository was on 2026-06-29, and there are no GitHub releases, since the versioning lives in the directory names rather than in tags.

The licence separates the text from what you build with it

The licence section is short but the distinction it draws matters more than the licence itself.

The text of the specification is licensed under a Creative Commons Attribution 3.0 United States License. However, the use of this spec in products and code is entirely free, with no royalties, restrictions or requirements.

So there are two grants in one paragraph. The prose that describes the format is a Creative Commons document, so if you quote the specification, for example in your own documentation, you attribute it. The format itself, the thing you encode and decode, is free to use with no conditions at all.

That split is a deliberate piece of legal engineering and it is a good pattern. A specification that is CC BY protects the integrity of the document without taxing the people implementing it, and it removes the question of whether using a format in a commercial product needs a licence negotiation.

Note that the repository's own licence metadata is not one GitHub classifies as a standard licence, so the `LICENSE` file at the root is the authoritative text rather than the metadata. The same pattern of a permissively licensed specification and an unclassified repository licence is common in standards bodies.

The repository also carries a `CODEOWNERS` file, a `CODE_OF_CONDUCT.md` and a `CONTRIBUTING.md`, which are the governance markers of a project that intends to keep the document stable and the contribution process open.

Translations, authors and the shape of the tree

Two smaller details in the README tell you how the project is run.

The first is the author list. Nine names are credited, including Vladimir Agafonkin, John Firebaugh, Eric Fischer, Konstantin Käfer, Charlie Loyd, Tom MacWright, Artem Pavlenko, Dane Springmeyer and Blake Thompson. That is a list spanning the original Mapbox era and the open source continuation, and it is a reasonable thing to look at if you want to know who to trust on a particular section of the text.

The second is the translations. The specification is available in Simplified Chinese, hosted in a separate repository by jingsam, and in Japanese, hosted by madefor. Both live outside this repository, which is the normal arrangement for a spec that wants a single source of truth for the normative text, with the translations maintained by the people who can do them well.

The tree itself is the other structural signal. Four version directories, each self-contained, plus the top level documents. There is no `src/`, no `test/`, no package manifest, and no build configuration of any kind. The `CHANGELOG.md` and the `CODEOWNERS` are the only files that suggest a software project, and both are there to support the document.

What that means in practice is that implementing the format means reading one of those four directories, probably `2.1/`, and writing code against it. There is nothing to install, nothing to build and nothing to keep in step with, and the only thing that can change is the text of the specification itself, under the versioning rules described earlier.

Where the specification stops

The limits here are the limits of any specification, and they are worth being explicit about before you commit.

The first is that the document describes bytes, not behaviour. It tells you what a layer contains, how the fields are defined and what the version number means. It does not tell you how to render a polygon with an interior ring correctly, how to handle a tile that crosses the antimeridian, or what to do with a geometry that is technically valid and visually wrong. Those are implementation problems, and they are where the interesting engineering lives.

The second is the age. The current version, 2.1, was released on January 19, 2016, and 2.0, which is the version that clarified the polygon ring definitions that most implementations depend on, is from December 2015. The repository is not archived and the last push was on 2026-06-29, so the document is maintained, but there is no evidence in the version history of a format change since 2016. That is not a flaw, since a stable format is the point, but a team choosing a tile format for a new product in 2026 should know it is choosing a format that has been stable for a decade and ask whether that stability is a feature or a constraint.

The third is that the specification is Mapbox's. The homepage for the specification is on mapbox.com, the implementations list lives in a Mapbox repository, and the licence grants free use but the document is authored and maintained under Mapbox's name. For an open standard in practice, that matters less than it might, since the format is implemented widely and the licence imposes nothing, but it is the fact behind the name.

The alternative approach, and the difference in approach is real, is to not use vector tiles at all and to serve raster tiles or to render vectors on the client from GeoJSON or from your own tile format. That trades the compactness and the fact that the geometry is resolved before it reaches the client for a simpler pipeline and a smaller set of moving parts. The choice depends on whether your bottleneck is bandwidth and server rendering cost, or the complexity of a vector pipeline, and the specification is only interesting if the former is the binding constraint.

Editorial conclusion

The specification suits an engineer implementing a vector tile encoder or decoder, or a team deciding which tile format to build on, because it is the normative text rather than one vendor's implementation. It is the wrong thing to adopt if you need a library, a renderer or a server, since none of those are in this repository, and it is worth checking the age of the format before committing. Check the version field your data carries, because the major version is what a decoder uses to decide how to read the layer, and note that the 2.1 text dates from 2016 and the last push was on 2026-06-29.

Frequently asked questions

Official sources

1. Issues
2. mapbox/vector-tile-spec on GitHub
3. Project website
4. README