Extended TileJSON 3.0

Status Implemented | Last updated 2025-11-04

Introduction

This extension defines four optional metadata fields for the TileJSON 3.0 spec, enabling clients to understand tile content before downloading the first tile. These fields allow clients to pre-configure appropriate renderers and display fallback messages when unsupported tile types are encountered. Clients and servers that do not recognize these properties remain fully compatible, as this extension adds no required fields and preserves existing TileJSON semantics.

Why extend TileJSON?

1. Clients cannot determine whether tiles are raster or vector. Therefore, we add tile_type.
2. Clients cannot determine whether tiles are RGB imagery, DEM, or other types. Therefore, we add tile_schema.
3. Clients cannot determine whether tiles are served as JPEG, PNG, or other formats. Therefore, we add tile_format.
4. Clients cannot determine whether image tiles have standard (256×256) or high resolution (512×512). Therefore, we add tile_size.
5. Neither tile source generators nor servers know the exact URLs under which tiles will be served. Therefore, we relax the rules for URLs in tiles.

---

Property tile_type

tile_type indicates whether the source is a "raster" or "vector" tile source. All values must be lowercase.

Value	Meaning
raster	Pixel tiles (imagery, DEM, etc.)
vector	Geometry/feature tiles (MVT, MLT)
unknown	Other types

---

Property tile_schema

tile_schema describes how to interpret the data. All values must be lowercase and follow the pattern <family>[/<subtype>][@<version>]

Raster values

Value	Use case
rgb	3-band imagery (no alpha)
rgba	4-band imagery with alpha
dem/mapbox	Elevation data in Mapbox Terrain-RGB format
dem/terrarium	Elevation data in Mapzen Terrarium format
dem/versatiles	Placeholder for a future VersaTiles DEM

Vector values

Value	Vector tiles follow…
openmaptiles	The OpenMapTiles schema
shortbread@1.0	The Shortbread 1.0 schema
other	An unspecified, unknown, or custom schema

NOTE

Versioning recommendation: If a schema has formal versions, append them after @, e.g., shortbread@1.0.

---

Property tile_format

Any valid media type is allowed. All values must be lowercase. Non-standard types should use the vnd.* or x.* tree. The server should send tile content with the same Content-Type as defined in tile_format.

Common raster formats

Value	Meaning
image/png	PNG images
image/jpeg	JPEG images
image/webp	WebP images
image/avif	AVIF images

Common vector formats

Value	Notes
application/vnd.mapbox-vector-tile	Tiles follow the Mapbox Vector Tile Specification

NOTE

MapLibre is developing the MapLibre Tile specification and may register its own MIME type in the future.

---

Property tile_size

tile_size defines the size of tiles as a number. This applies only to raster tiles. The value should be 256 or 512. Fractional or larger sizes (e.g., 1024) are allowed but not recommended.

---

Relaxed rule for tiles

The TileJSON 3.0 spec requires absolute URLs in the tiles property. This was designed with the assumption that tiles are served from a single, known domain. For self-hosted tile servers, this assumption does not hold:

• Hardcoding the server URL at startup breaks when the server is behind a CDN, a reverse proxy, or reachable under multiple hostnames.
• Deriving the URL from the HTTP request requires correct forwarding of Host and X-Forwarded-* headers through every proxy, adding fragile configuration.

Since TileJSON references resources on the same host under the same path prefix, this is precisely the use case relative URLs were designed for.

Rule

• tiles may contain relative URL templates.
• Each URL must be resolved relative to the JSON document’s own location.

Example

The file at https://example.org/tiles/osm/tiles.json contains:

{
  "tiles": ["{z}/{x}/{y}"],
  …
}

A client resolves this to https://example.org/tiles/osm/{z}/{x}/{y}.

Client implementation note

WARNING

JavaScript’s URL class will percent-encode curly braces in template variables (e.g. %7Bz%7D instead of {z}). After resolving, replace %7B → { and %7D → }:

function resolveUrl(base, url) {
  url = new URL(url, base).href;
  return url.replace(/%7B/gi, ‘{‘).replace(/%7D/gi, ‘}’);
}

---

Examples

Terrarium DEM tiles (WebP)

{
  "tilejson": "3.0.0",
  "name": "Global Hillshade (Terrarium)",
  "bounds": [-180, -85, 180, 85],
  "minzoom": 0,
  "maxzoom": 14,
  "tiles": ["{z}/{x}/{y}"],

  "tile_type": "raster",
  "tile_format": "image/webp",
  "tile_schema": "dem/terrarium",
  "tile_size": 512
}

OSM vector tiles in the Shortbread schema

{
  "tilejson": "3.0.0",
  "name": "OSM Vector — Shortbread",
  "tiles": ["{z}/{x}/{y}"],

  "tile_type": "vector",
  "tile_format": "application/vnd.mapbox-vector-tile",
  "tile_schema": "shortbread@1.1"
}