TileJSON
Feb 25,2026

GISBox is a one-stop 3D GIS data editing, conversion and publishing platform that supports editing in multiple GIS formats such as OSGB/GEOTIFF/RVT, converting to 3DTiles/Terrain and publishing.

Introduction

TileJSON is an open standard for describing map tile layers and their capabilities in a machine-readable JSON format. Originally developed by Mapbox as a specification for their mapping platforms, it has since evolved into a widely adopted community standard for declaring metadata about tile sets—whether they are raster tiles, vector tiles, or terrain tiles. A TileJSON file provides a structured, human-readable, and developer-friendly way to communicate essential information such as the tile server's endpoint URL, the tile format (PNG, MVT, GeoTIFF, etc.), the spatial extent (bounds), the coordinate reference system (commonly Web Mercator - EPSG:3857), the minimum and maximum zoom levels, attribution requirements, and other descriptive metadata. This standard enables map clients, styling tools, and data catalogues to automatically discover and consume tile services without requiring manual configuration or prior knowledge of the tile source's internal structure.

File Structure

TileJSON is a structured JSON document containing core properties that define a tile service. Key fields include tiles (array of tile endpoint URLs with {z}/{x}/{y} placeholders), name and description for identification, attribution for required credit text, bounds for geographic extent in WGS84, minzoom and maxzoom for available zoom levels, and format for tile encoding (PNG, MVT, etc.). Optional extensions like vector_layers provide detailed schema information for vector tile attribute fields. This lightweight, self-describing format enables clients to automatically configure map sources without prior knowledge of the service.

Pros

Interoperability and Standardization: Provides a universally understood format for describing tile services, enabling any TileJSON-compliant client (such as MapLibre GL, OpenLayers, ArcGIS, or QGIS) to consume and render tiles without custom integration code.
Simplicity and Human Readability: The JSON format is easy to read, write, and debug for developers, while remaining machine-parseable, striking an ideal balance for configuration and API responses.
Self-Describing Tile Services: A single TileJSON file contains all necessary metadata—attribution, bounds, zoom levels, and format—eliminating guesswork and manual configuration when integrating new tile sources.
Wide Ecosystem Adoption: Supported natively by virtually all modern web mapping libraries, mobile SDKs, and desktop GIS applications, making it the de facto standard for publishing tile services in contemporary geospatial applications.
Extensibility: The JSON structure allows for custom properties beyond the specification, enabling providers to include additional metadata while maintaining backward compatibility.

Cons

Limited to Tile Services: TileJSON is specifically designed for tiled map data and cannot describe other geospatial service types such as WMS, WFS, or feature APIs, limiting its scope to tile-based workflows.
Potential for Incomplete Implementations: Not all properties are mandatory, and some tile providers may omit important fields like attribution or bounds, leading to inconsistent user experiences across different clients.
Static Nature: TileJSON files are typically static documents that do not dynamically reflect changes in the underlying tile service (e.g., new zoom levels becoming available), requiring manual updates when tile sets evolve.
Vector Tile Layer Descriptions Can Be Sparse: While the vector_layers extension exists, its adoption varies, and many vector tile services provide minimal or incomplete field descriptions, reducing the utility for advanced client-side styling and querying.
No Standardized Validation Mechanism: Unlike XML-based schemas with formal validation tools, TileJSON lacks a widely adopted, strict validation framework, leading to potential parsing errors across different client implementations.

Application Scenario

TileJSON serves as the foundational discovery and configuration layer for modern web and mobile mapping applications that consume pre-rendered tile services. It enables map clients to automatically configure sources—handling zoom constraints, attribution display, and tile URL construction—by simply referencing a TileJSON endpoint or embedding its contents. In vector tile workflows, TileJSON files are referenced within style specifications to define data sources for styling rules. Geospatial data catalogues and marketplaces use TileJSON to publish discoverable tile layers with proper attribution and technical specifications, while mobile mapping SDKs consume it to guide offline tile pre-caching based on bounds and zoom ranges. Its strength lies in transforming tile services from opaque endpoints into self-documenting resources that integrate seamlessly into the broader geospatial software ecosystem.