Что такое JSON Schema

JSON Schema — это JSON-документ, который описывает, как должен выглядеть другой JSON-документ. Стандарт поддерживается JSON Schema Foundation, актуальная версия — Draft 2020-12.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["item_id", "event", "timestamp"],
  "properties": {
    "item_id":   { "type": "string" },
    "event":     { "type": "string", "enum": ["view_item", "add_to_cart", "purchase"] },
    "timestamp": { "type": "integer", "description": "Unix timestamp в миллисекундах" },
    "price":     { "type": "number", "minimum": 0 }
  }
}

Такая схема однозначно говорит: объект обязан содержать item_id, event и timestamp; значение event — только из списка; price — неотрицательное число. Любой JSON-валидатор проверит входящие данные за доли секунды.

Применение в e-commerce интеграциях

Валидация product feed

Для платформ персонализации product feed — критический источник данных. Типичная схема фида включает:

Поле Тип Обязательное
id string Да
title string Да
price number Да
availability enum: in_stock / out_of_stock Да
category_path array of strings Рекомендуется
images array of URLs Рекомендуется

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

Контракт событийных данных

Каждое событие аналитики (просмотр, клик, покупка) описывается своей схемой. Это защищает от случайных изменений в коде фронтенда — если разработчик переименует поле item_id в product_id, CI-pipeline немедленно выдаст ошибку валидации.

Совет: храните схемы событий в репозитории рядом с кодом интеграции. При обновлении платформой формата события — обновляйте схему как часть того же PR. Это избавляет от «тихих» нарушений контракта.

Инструменты валидации

  • ajv (Node.js) — самый быстрый валидатор, поддерживает все актуальные черновики стандарта
  • jsonschema (Python) — стандартный выбор для Python-пайплайнов обработки фидов
  • Swagger / OpenAPI — использует JSON Schema как основу для описания REST API; IDE-плагины дают встроенную валидацию
  • Postman / Bruno — встроенная проверка ответов по схеме в тестах API