Tile JSON спецификация

TileJSON представляет собой стандартизированный формат описания наборов тайлов (tilesets), используемый в веб-картографии для унифицированного доступа к растровым и векторным тайлам. Он служит промежуточным слоем между источником пространственных данных и клиентскими библиотеками, включая Mapbox GL JS, обеспечивая согласованное описание структуры, диапазонов масштабов и URL-шаблонов для загрузки тайлов.

TileJSON решает задачу абстрагирования источника тайлов от способа их потребления. Вместо жестко заданных URL или локальных путей клиент получает метаданные, описывающие:

  • формат тайлов (vector, raster)
  • шаблоны доступа к тайлам
  • географические границы покрытия
  • допустимые масштабы
  • центрирование карты по умолчанию
  • служебные атрибуты (attribution)

Такой подход делает возможным динамическую подмену источников данных без изменения клиентского кода, что критично для библиотек визуализации, таких как Mapbox GL JS.

Структура TileJSON-документа

TileJSON описывается JSON-объектом верхнего уровня, содержащим фиксированный набор полей. Несмотря на гибкость JSON, спецификация предполагает строгую семантику ключей.

Базовые поля

tilejson

Версия спецификации TileJSON.

Пример:

"tilejson": "3.0.0"

Используется для определения совместимости клиента и источника данных.

name

Человекочитаемое имя набора тайлов.

description

Описание слоя, его содержания и назначения.

Описание источников тайлов

tiles

Ключевой элемент спецификации — массив URL-шаблонов:

"tiles": [
  "https://example.com/tiles/{z}/{x}/{y}.pbf"
]

Поддерживаются подстановочные параметры:

  • {z} — уровень масштаба
  • {x} — координата по оси X
  • {y} — координата по оси Y

Для повышения производительности допускается несколько URL, которые используются как пул серверов (load balancing на уровне клиента).

vector_layers

Используется для векторных тайлов (MVT — Mapbox Vector Tile). Описывает логическую структуру слоев внутри тайла:

"vector_layers": [
  {
    "id": "roads",
    "fields": {
      "name": "String",
      "type": "String"
    }
  }
]

Этот блок не обязателен, но существенно упрощает интерпретацию данных на клиенте, особенно при стилизации в Mapbox GL JS.

Географические параметры

bounds

Географический bounding box набора тайлов:

"bounds": [-180, -85.0511, 180, 85.0511]

Формат:

[west, south, east, north]

Используется для ограничения видимой области и оптимизации загрузки данных.

center

Определяет начальный центр карты и уровень масштаба:

"center": [-73.9857, 40.7484, 12]

Формат:

[longitude, latitude, zoom]

minzoom и maxzoom

Ограничивают диапазон доступных масштабов:

"minzoom": 0,
"maxzoom": 14

Эти параметры важны для корректного планирования запросов к серверу тайлов и предотвращения обращения к несуществующим уровням детализации.

Атрибуция и лицензирование

attribution

Поле, содержащее текст обязательного указания источника данных:

"attribution": "© OpenStreetMap contributors"

В контексте веб-картографии атрибуция является не только юридическим требованием, но и частью пользовательского интерфейса, который динамически отображается в клиентах визуализации, включая Mapbox GL JS.

Схема тайлов

scheme

Определяет систему координат тайлов:

  • "xyz" — стандартная веб-схема (Y растет вниз)
  • "tms" — Tile Map Service (Y растет вверх)

Пример:

"scheme": "xyz"

Большинство современных картографических стеков используют xyz как дефолтное значение.

Форматы данных

TileJSON не ограничивает тип данных, но чаще всего используются:

  • Raster tiles — изображения (PNG, JPG)
  • Vector tiles — бинарный формат Mapbox Vector Tile (PBF)

Векторные тайлы являются основой динамической стилизации в Mapbox GL JS, поскольку позволяют применять стили на стороне клиента без перерисовки изображений.

Поле minresolution и расширения спецификации

Некоторые реализации добавляют нестандартные поля:

  • format — явное указание типа тайлов (pbf, png, jpg)
  • legend — описание легенды слоя
  • template — HTML-шаблон описания объектов
  • grids — устаревший механизм UTFGrid

Хотя эти расширения не входят в базовую спецификацию, они часто поддерживаются экосистемами, связанными с Mapbox.

Связь TileJSON и Mapbox Style Specification

TileJSON часто используется как источник данных для стилей. В Mapbox Style Specification источник данных описывается через sources, где TileJSON может выступать промежуточным уровнем:

"sources": {
  "streets": {
    "type": "vector",
    "url": "https://example.com/tiles.json"
  }
}

В этом случае клиент сначала загружает TileJSON, затем извлекает tiles, minzoom, maxzoom и другие параметры.

Роль TileJSON в Mapbox GL JS

Внутри Mapbox GL JS TileJSON используется на этапе инициализации источников данных. Библиотека:

  1. Загружает TileJSON по URL
  2. Парсит метаданные
  3. Регистрирует источник как VectorSource или RasterSource
  4. Использует tiles для генерации запросов
  5. Применяет minzoom/maxzoom для оптимизации запросов
  6. Использует bounds для клиппинга и ограничения видимости

Такой подход позволяет отделить описание данных от их визуализации.

Производительность и кеширование

TileJSON напрямую влияет на стратегию кеширования:

  • неизменяемые tiles URL позволяют эффективно использовать HTTP cache
  • наличие нескольких серверов в tiles[] повышает параллелизм
  • корректные minzoom/maxzoom уменьшают количество ненужных запросов

Векторные тайлы особенно эффективны в связке с клиентской стилизацией, поскольку уменьшают общий объем передаваемых данных по сравнению с растровыми изображениями.

Ошибки и типичные проблемы интеграции

Некорректные шаблоны URL

Ошибки в {z}/{x}/{y} приводят к 404 и отсутствию тайлов на карте.

Несоответствие bounds

Если bounds не соответствует фактическим данным, карта может:

  • запрашивать пустые тайлы
  • обрезать доступную географию
  • некорректно центрироваться

Ошибки zoom-диапазона

Слишком узкий диапазон minzoom/maxzoom приводит к отсутствию данных при масштабировании.

Отсутствие attribution

Может нарушать лицензионные требования источника данных.

Взаимодействие с серверной частью

TileJSON часто генерируется динамически сервером, который агрегирует данные из:

  • PostGIS
  • MBTiles
  • облачных хранилищ (S3, GCS)
  • tile server решений (например, Tegola, TileServer GL)

Сервер формирует JSON-описание на основе метаданных слоя и публикует его как конечную точку API.

Роль TileJSON в масштабируемых картографических системах

В крупных системах TileJSON становится контрактом между:

  • генерацией тайлов
  • CDN-доставкой
  • клиентскими библиотеками (включая Mapbox GL JS)
  • системами стилизации и аналитики

Его простота позволяет использовать его как универсальный слой описания геоданных независимо от внутренней реализации источника.

Оглавление