Валидация JSON

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

В Mapbox GL JS источник данных добавляется через объект map.addSource, где тип источника часто задается как 'geojson'. Пример базового подключения источника:

map.addSource('places', {
    type: 'geojson',
    data: {
        type: 'FeatureCollection',
        features: []
    }
});

Если структура JSON нарушена, карта может либо не загрузить данные, либо вызвать ошибки JavaScript, что делает проверку валидности обязательной на этапе подготовки данных.

Структура GeoJSON и требования Mapbox GL JS

Ключевые элементы GeoJSON, которые Mapbox GL JS требует для корректной работы:

  1. FeatureCollection – основной контейнер для набора географических объектов:
{
    "type": "FeatureCollection",
    "features": []
}
  1. Feature – отдельный объект с геометрией и набором свойств:
{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [30.5, 50.5]
    },
    "properties": {
        "name": "Example"
    }
}
  1. Geometry – объект, определяющий форму: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection.

Ключевые правила:

  • coordinates должны быть массивами чисел. Для Point это [долгота, широта], для Polygon — массив массивов координат.
  • Все ключи и значения должны быть корректными JSON-типами: строки, числа, массивы, объекты, true/false, null.
  • GeoJSON требует строгого соответствия стандарту, иначе Mapbox GL JS не сможет обработать данные.

Валидация JSON на этапе разработки

1. Синтаксическая проверка

Наиболее простой способ убедиться в валидности JSON — использовать JSON.parse:

try {
    const geojson = JSON.parse(jsonString);
    console.log('JSON валиден');
} catch (e) {
    console.error('Ошибка JSON:', e.message);
}

Это проверяет только синтаксис, но не структуру GeoJSON.

2. Проверка структуры GeoJSON

Для проверки структуры GeoJSON применяются специализированные библиотеки, такие как geojsonhint. Она анализирует объект и возвращает список ошибок, если структура некорректна:

import geojsonhint from '@mapbox/geojsonhint';

const errors = geojsonhint.hint(geojson);
if (errors.length === 0) {
    console.log('Структура GeoJSON корректна');
} else {
    console.error('Ошибки GeoJSON:', errors);
}

Типичные ошибки, выявляемые при проверке:

  • Отсутствие поля type у объекта Feature или FeatureCollection.
  • Неправильный тип геометрии (geometry.type не соответствует стандарту).
  • Неправильный формат массива координат (например, вложенность или порядок [долгота, широта] нарушены).
  • Пустые массивы features или coordinates, что может вызвать предупреждения Mapbox GL JS.

3. Проверка типов данных

Mapbox GL JS не проверяет типы свойств объектов, поэтому важно убедиться, что данные соответствуют ожидаемым типам для стилей и фильтров:

features.forEach(feature => {
    if (typeof feature.properties.name !== 'string') {
        console.warn('Некорректный тип свойства name');
    }
});

Практика валидации данных перед добавлением на карту

  1. Локальная проверка перед загрузкой – предотвращает ошибки на клиенте и позволяет заранее исправить некорректные объекты.
  2. Автоматическая валидация при загрузке через fetch:
fetch('data.geojson')
    .then(response => response.json())
    .then(data => {
        const errors = geojsonhint.hint(data);
        if (errors.length === 0) {
            map.addSource('places', { type: 'geojson', data });
        } else {
            console.error('Ошибки GeoJSON:', errors);
        }
    });
  1. Использование схем JSON (JSON Schema) для строгой валидации и интеграции с CI/CD: позволяет автоматически проверять все новые файлы данных перед деплоем.

Валидация свойств данных для Mapbox GL JS

Mapbox GL JS использует стили и фильтры, основанные на свойствах Feature:

map.addLayer({
    id: 'points',
    type: 'circle',
    source: 'places',
    paint: {
        'circle-radius': ['get', 'radius'],
        'circle-color': ['get', 'color']
    }
});

Если свойства отсутствуют или имеют неправильный тип (например, radius — строка вместо числа), слой не отобразится корректно.

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

Инструменты для автоматизации проверки JSON

  • geojson.io – визуальная проверка и отладка GeoJSON.
  • geojsonhint – линтер для программной проверки структуры.
  • ESLint с плагинами для JSON – позволяет проверять синтаксис и структуру в проекте.
  • JSON Schema + AJV – строгая валидация всех полей и типов.

Валидация на серверной стороне

Для больших проектов полезно проверять JSON перед отправкой на фронтенд:

  • Проверка корректности структуры GeoJSON.
  • Проверка координат на допустимые диапазоны (-180…180 долгота, -90…90 широта).
  • Проверка уникальности идентификаторов объектов.
  • Логирование ошибок для последующей коррекции данных.

Практическое правило

Любой JSON, передаваемый в Mapbox GL JS, должен пройти три уровня проверки:

  1. Синтаксис JSON — отсутствие ошибок парсинга.
  2. Структура GeoJSON — правильные объекты Feature и FeatureCollection.
  3. Типы и свойства данных — соответствие требованиям слоев и фильтров Mapbox GL JS.

Следование этим правилам предотвращает большинство ошибок при визуализации данных и позволяет строить сложные интерактивные карты без неожиданных сбоев.

Оглавление