Формат JSON спецификации

Формат JSON в Mapbox GL JS определяет стиль карты, источники данных и правила их визуализации. Это центральная часть архитектуры рендеринга, где вся карта описывается декларативно через структуру JSON, а не через императивный код.

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

Ключевые поля:

  • version — версия спецификации стиля
  • name — человекочитаемое имя стиля
  • metadata — произвольные пользовательские данные
  • sources — источники геоданных
  • sprite — спрайт с иконками
  • glyphs — шаблон URL для шрифтов
  • layers — массив слоёв отрисовки
  • light — параметры освещения (3D)
  • transition — настройки анимации переходов

Минимально валидный стиль уже должен содержать version, sources и layers, даже если они пустые.

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

Поле version фиксирует версию JSON-спецификации стиля. На практике используется значение 8, которое соответствует современному формату Mapbox Style Specification.

{
  "version": 8
}

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

Источники данных (sources)

Раздел sources определяет, откуда берутся географические данные. Каждый источник имеет уникальный идентификатор и набор параметров.

Общая структура:

"sources": {
  "my-source": {
    "type": "vector",
    "url": "mapbox://mapbox.terrain-v2"
  }
}

Типы источников

Vector source

Использует векторные тайлы.

Параметры:

  • type: "vector"
  • url или tiles
  • minzoom, maxzoom
{
  "type": "vector",
  "url": "mapbox://mapbox.mapbox-streets-v8"
}

Raster source

Растровые тайлы изображений.

{
  "type": "raster",
  "tiles": ["https://example.com/tiles/{z}/{x}/{y}.png"],
  "tileSize": 256
}

GeoJSON source

Локальные или удалённые GeoJSON данные.

{
  "type": "geojson",
  "data": {
    "type": "FeatureCollection",
    "features": []
  }
}

Image source

Используется для наложения изображения на координаты.

{
  "type": "image",
  "url": "image.png",
  "coordinates": [
    [-80, 37],
    [-80, 35],
    [-78, 35],
    [-78, 37]
  ]
}

Слои (layers)

Слои — основная единица визуализации. Каждый слой описывает, как данные из источника должны отображаться.

Структура слоя:

{
  "id": "water",
  "type": "fill",
  "source": "my-source",
  "source-layer": "water",
  "paint": {
    "fill-color": "#00ffff"
  }
}

Порядок слоёв

Слои отрисовываются строго последовательно: каждый следующий слой накладывается поверх предыдущего. Порядок в массиве layers критически важен.

Типы слоёв

Fill

Используется для полигонов.

{
  "type": "fill",
  "paint": {
    "fill-color": "#088",
    "fill-opacity": 0.5
  }
}

Line

Линии и контуры.

{
  "type": "line",
  "paint": {
    "line-color": "#000",
    "line-width": 2
  }
}

Symbol

Тексты и иконки.

{
  "type": "symbol",
  "layout": {
    "text-field": "{name}",
    "text-size": 12
  }
}

Circle

Точечные объекты.

{
  "type": "circle",
  "paint": {
    "circle-radius": 6,
    "circle-color": "#f00"
  }
}

Raster

Отображение растровых тайлов.

Fill-extrusion

3D-экструзия зданий.

{
  "type": "fill-extrusion",
  "paint": {
    "fill-extrusion-height": 50,
    "fill-extrusion-color": "#aaa"
  }
}

Heatmap

Плотностные карты.

Hillshade

Тени рельефа.

Layout и Paint

Каждый слой делится на два блока:

  • layout — геометрия и структура отображения
  • paint — визуальное оформление

Layout свойства

Примеры:

  • размещение текста
  • видимость слоя
  • поворот иконок
"layout": {
  "visibility": "visible",
  "text-field": "{label}",
  "text-font": ["Open Sans Regular"]
}

Paint свойства

Отвечают за внешний вид:

  • цвета
  • прозрачность
  • ширина линий
  • радиусы точек
"paint": {
  "line-color": "#ff0000",
  "line-width": 3
}

Expressions (выражения JSON)

Mapbox GL JS использует декларативные выражения, записанные в JSON-массиве.

Пример интерполяции:

"line-width": [
  "interpolate",
  ["linear"],
  ["zoom"],
  5, 1,
  10, 4
]

Условные выражения:

"circle-color": [
  "case",
  ["==", ["get", "type"], "park"],
  "#00ff00",
  "#ff0000"
]

Основные операторы:

  • get
  • match
  • case
  • interpolate
  • step
  • zoom

Filters

Фильтры определяют, какие объекты отображаются в слое.

"filter": ["==", "class", "water"]

Поддерживаются логические операции:

  • ==, !=
  • >, <, >=, <=
  • all, any, none
  • in

Source-layer

Для векторных тайлов используется поле source-layer, указывающее на слой внутри тайла.

{
  "source": "composite",
  "source-layer": "building"
}

Это критически важно, так как один источник может содержать множество логических слоёв.

Sprite и Glyphs

Sprite

Определяет набор иконок:

"sprite": "mapbox://sprites/mapbox/streets-v11"

Glyphs

Шаблон шрифтов:

"glyphs": "mapbox://fonts/mapbox/{fontstack}/{range}.pbf"

Transition

Настройки анимации изменений свойств:

"transition": {
  "duration": 300,
  "delay": 0
}

Применяется ко всем анимируемым параметрам (цвет, ширина, прозрачность).

Light (3D освещение)

Используется для 3D слоёв:

"light": {
  "anchor": "viewport",
  "intensity": 0.5,
  "color": "#ffffff"
}

Полный пример Style JSON

{
  "version": 8,
  "name": "Custom Style",
  "sprite": "mapbox://sprites/mapbox/streets-v11",
  "glyphs": "mapbox://fonts/mapbox/{fontstack}/{range}.pbf",
  "sources": {
    "streets": {
      "type": "vector",
      "url": "mapbox://mapbox.mapbox-streets-v8"
    }
  },
  "layers": [
    {
      "id": "background",
      "type": "background",
      "paint": {
        "background-color": "#f0f0f0"
      }
    },
    {
      "id": "roads",
      "type": "line",
      "source": "streets",
      "source-layer": "road",
      "paint": {
        "line-color": "#333",
        "line-width": 2
      }
    }
  ],
  "transition": {
    "duration": 200
  }
}

Структурные особенности спецификации

JSON-формат стиля в Mapbox GL JS является строго декларативным. Это означает:

  • отсутствие логики выполнения
  • отсутствие функций
  • отсутствие состояния
  • вся динамика реализуется через expressions

Каждый элемент стиля описывает только правила отображения, а не алгоритм обработки.

Типизация значений

В спецификации используются строго определённые типы:

  • Color — строки "#RRGGBB" или rgba
  • Number — числовые значения
  • Array — списки (в том числе expressions)
  • String — текстовые поля
  • Boolean — true/false

Некоторые свойства допускают zoom-dependent значения:

"circle-radius": {
  "stops": [
    [0, 2],
    [10, 10]
  ]
}

(в современных версиях заменено expressions)

Декларативная модель рендеринга

Стиль JSON формирует граф слоёв, где:

  • источники предоставляют данные
  • слои фильтруют и визуализируют их
  • paint/layout задают визуальные правила
  • expressions вычисляют динамику

Рендерер Mapbox GL JS интерпретирует этот JSON в GPU-пайплайн, преобразуя декларативное описание в набор WebGL команд без необходимости ручного управления отрисовкой

Оглавление