Что JSON Schema реально решает
Главное: Schema управляет структурой и типами, а не бизнес-смыслом. Она останавливает отсутствующие поля, неверные типы и перечисления вне диапазона, а правила вроде суммы больше нуля остаются в коде.
Главное: пусть JSON Schema обеспечивает структуру, типы, диапазоны и форматы, а межполевые правила, бизнес-инварианты и внешнее состояние остаются в коде; внедряйте её для публичных API и общих полезных нагрузок, а не для внутреннего сервиса с пятью полями.
Она отвечает на вопрос «правильно ли сформированы эти данные», а не «имеют ли эти данные смысл».
Что она делает хорошо
Структурная полнота. Какие поля должны существовать, разрешены ли лишние (required, additionalProperties).
Типы. port как число или строка, tags как массив или скаляр. Уже это удаляет массу защитного кода в многоязыковых системах.
Диапазоны. enum, minimum/maximum, длина строки и массива.
Форматы. format для дат, email, URI и UUID, с валидаторами, которые их обеспечивают.
Вложенность. Каждый уровень объектов и массивов получает свои ограничения, а ошибки несут точный путь.
Документация. Schema — это контракт. Измените поле, и различие покажет радиус поражения. Она также генерирует типы и формы, так что одно определение питает несколько потребителей.
Что она не может
Межполевые зависимости. «Конец должен быть после начала» можно выразить через if/then/else, но результат длиннее и труднее для чтения, чем три строки кода.
Бизнес-инварианты. «Запас не может стать отрицательным» зависит от внешнего состояния. Schema видит один документ.
Семантику. price: -100 прекрасно удовлетворяет {"type": "number"}. Легальна ли это цена — вне знания Schema.
Рабочее разделение
| Слой | Владелец |
|---|---|
| Синтаксис: валидный ли это JSON | Парсер |
| Структура: поля, типы, диапазоны, форматы | JSON Schema |
| Семантика: межполевое, бизнес-правила, внешнее состояние | Код приложения |
| Безопасность: размер, глубина, частота | Шлюз / промежуточное ПО |
Схлопните это в одно место, и Schema разрастётся до сотен строк с пятью уровнями if/then. В этот момент люди обходят её стороной.
Когда это окупается
- Публичные API с неизвестными потребителями
- Несколько сервисов, читающих одну полезную нагрузку
- Системы на конфигурации, где опечатки должны падать быстро
- Генерация типов или форм из контракта
Для небольшого внутреннего сервиса с пятью полями и одним фронтендом написанные вручную проверки быстрее в сопровождении. Внедрять там Schema — отрицательная работа.
Вопросы и ответы
Как решить, внедрять ли JSON Schema?
Взвесьте публичных потребителей, несколько сервисов, читающих одну полезную нагрузку, и потребность генерировать типы или формы. Для небольшого внутреннего сервиса с пятью полями и одним фронтендом написанные вручную проверки быстрее в сопровождении.
Почему межполевые правила должны оставаться в коде?
«Конец должен быть после начала» можно втиснуть в if/then/else, но результат длиннее и труднее для чтения, чем несколько строк кода. Schema также не видит внешнее состояние.
Должна ли Schema валидировать размер полезной нагрузки и глубину вложенности?
Нет. Schema описывает структуру, а не размер или глубину; эти лимиты принадлежат шлюзу или слою промежуточного ПО.