Developer

JSON Schema: описание структуры и валидация

↑ 1.4 JSON, XML и другие форматы · ← Предыдущая · → Следующая

Обязательно~5 мин чтенияУровень: junior

Зачем это аналитику и PM

Список полей в вики устаревает молча. JSON Schema — тот же список в виде, который можно прогнать по примеру: обязательность, тип, набор статусов. Расхождение примера и схемы видно до приёмки.

План темы

  • required, type, enum, формат
  • зачем схема аналитику
  • примеры

Объяснение

JSON Schema — текст на JSON, который описывает, какой другой JSON считать подходящим по форме. Это не сами данные заказа, а правила формы: какие ключи нужны, какого они типа, какие строки статуса допустимы.

Как трафарет на анкету. Трафарет не заполняет графы за человека. Он не пускает анкету, где нет артикула, где количество написано словом или где статус выдуман. Смысл «нельзя продать больше остатка» трафарет обычно не знает: это уже правило предметной области, его проверяет сервер отдельно.

Какие слова встречаются сразу

type задаёт тип: object, array, string, integer, number, boolean, null. properties описывает поля объекта. required перечисляет ключи, без которых документ не подходит. Отсутствие ключа из required — ошибка формы, даже если в тексте «и так понятно». enum — закрытый список значений. Поле format в схемах бывает для строки, например дата-время, но набор форматов и строгость проверки зависят от библиотеки.

Черновик стандарта (draft) тоже часть файла. В примерах ниже его нет специально: показан общий минимум слов type, properties, required, enum, minimum. Какой черновик подключать, пишут в репозитории команды. Слова минимума у живых черновиков совпадают достаточно, чтобы читать чужую схему, но редкие ключи без версии лучше не копировать.

Зачем это аналитику

Схемой фиксируют договор раньше кода. Пример успешного заказа кладут рядом и проверяют, что он проходит. Пример отказа по форме кладут тоже: строка вместо числа не должна проходить. Бизнес-отказ «мало на складе» схема не заменяет. В постановке полезно разделить «не та форма» и «форма верная, правило не пустило». Первое ловит схема, второе — тест сценария.

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

Примеры

Схема и два документа ниже прогнаны проверяющим Draft 2020-12 библиотеки jsonschema: первый документ подходит, второй нет. Это учебная схема, не контракт магазина.

{
  "type": "object",
  "required": ["sku", "qty"],
  "properties": {
    "sku": {"type": "string"},
    "qty": {"type": "integer", "minimum": 1},
    "status": {"type": "string", "enum": ["new", "packed"]}
  },
  "additionalProperties": false
}

Подходит:

{"sku": "MUG-1", "qty": 2, "status": "new"}

Не подходит: qty строка, хотя выглядит цифрой.

{"sku": "MUG-1", "qty": "2"}

additionalProperties: false в этой схеме запрещает посторонние ключи. Если в вашем API лишние поля наоборот нужно пропускать, это слово не копируют. Решение одно на контракт.

Нюансы и подводные камни

  • Схема проверяет форму, не остаток склада и не права. Оба слоя в задаче названы отдельно.
  • integer не принимает дробь и не принимает число в кавычках. Для денег это часто повод выбрать другой тип, как в теме про числа.
  • required не подставляет значение по умолчанию. Чем заполнять пропущенное поле, пишут словами, если это вообще можно.

Практика

Для метода «создать позицию» набросайте минимум: два обязательных поля, тип количества и два допустимых статуса. Прогоните один хороший и один плохой пример тем способом, который есть у команды. Если способа нет, пометьте примеры как ожидаемые, не как уже проверенные.

Ожидаемый результат: у хорошего примера есть все ключи из required и статус из списка. У плохого сломан ровно один пункт формы, и вы можете сказать какой. Бизнес-правило «мало на складе» в эту схему не спрятано.

Вопросы с ответами

Связано с блоком Developer

Связанные темы

Вид графа

Обратные ссылки