Що JSON Schema справді вирішує
Головне: Schema керує структурою й типами, а не бізнес-сенсом. Вона зупиняє відсутні поля, неправильні типи й позадіапазонні переліки, тоді як правила на кшталт «сума понад нуль» залишаються в коді.
Коротко: дозвольте JSON Schema забезпечувати структуру, типи, діапазони й формати, тоді як правила між полями, бізнес-інваріанти й зовнішній стан залишайте в коді; впроваджуйте її для публічних API й спільних навантажень, а не для внутрішнього сервісу з пʼятьма полями.
Вона відповідає «чи ці дані правильної форми», а не «чи ці дані мають сенс».
З чим вона добре справляється
Структурна повнота. Які поля мусять існувати, чи дозволені зайві (required, additionalProperties).
Типи. port як число чи рядок, tags як масив чи скаляр. Лише це прибирає багато захисного коду в багатомовних системах.
Діапазони. enum, minimum/maximum, довжина рядка й масиву.
Формати. format для дат, email, URI й UUID, з валідаторами, що їх забезпечують.
Вкладеність. Кожен рівень обʼєктів і масивів отримує власні обмеження, а помилки несуть точний шлях.
Документація. Schema — це контракт. Змініть поле — і diff покаже радіус ураження. Вона також генерує типи й форми, тож одне визначення годує кілька споживачів.
Чого вона не може
Залежності між полями. «Кінець мусить бути після початку» можна виразити через 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 описує структуру, а не розмір чи глибину; ці ліміти належать шару шлюзу або проміжного ПЗ.