API принимает запросы без валидации структуры, и рано или поздно кто-то отправляет число вместо строки или забывает обязательное поле, а сервер падает где-то в глубине бизнес-логики с невнятной ошибкой. JSON Schema решает это на входе, до того как невалидные данные доберутся до кода приложения.
Минимальная рабочая схема
{
"type": "object",
"properties": {
"email": { "type": "string" },
"age": { "type": "integer" }
},
"required": ["email"]
}Этого достаточно для базовой проверки: объект с полем email обязательно строкового типа, полем age целочисленного типа, при этом email обязателен, а age — нет, потому что его нет в списке required.
Ключевые слова, которые закрывают почти все практические случаи
| Ключевое слово | Что делает | Пример |
|---|---|---|
| type | Задает тип значения | “string”, “integer”, “boolean”, “array”, “object” |
| required | Список обязательных полей объекта | [“email”, “name”] |
| minLength / maxLength | Ограничение длины строки | “minLength”: 3 |
| minimum / maximum | Ограничение числового диапазона | “minimum”: 0, “maximum”: 150 |
| enum | Список допустимых значений | [“admin”, “user”, “guest”] |
| format | Проверка распространенного формата строки | “email”, “date-time”, “uri” |
Пример со всеми ограничениями сразу
{
"type": "object",
"properties": {
"email": { "type": "string", "format": "email" },
"role": { "type": "string", "enum": ["admin", "user", "guest"] },
"age": { "type": "integer", "minimum": 0, "maximum": 150 }
},
"required": ["email", "role"]
}Эта схема уже отклонит запрос с некорректным email по формату, с ролью, которой нет в списке допустимых, или с отрицательным возрастом — без единой строчки ручной проверки внутри кода обработчика запроса.
Как быстро получить черновик схемы, а не писать с нуля
Писать схему руками для объекта с двумя десятками полей утомительно. JSON Schema Generator берет реальный пример JSON ответа и собирает по нему черновик схемы автоматически — типы определяются по значениям примера, а дальше остается только подправить конкретные ограничения вроде format или enum там, где это важно для вашей логики.
Ограничение автоматической генерации
Сгенерированная по одному примеру схема считает все поля примера обязательными, потому что других данных для сравнения у генератора просто нет. Список required почти всегда стоит вручную подрезать под реальные требования API, оставив только те поля, без которых запрос действительно не имеет смысла.
Итоговый чеклист
Базовой связки type, required и enum достаточно для подавляющего большинства практических случаев валидации входящих запросов API.
Ключевое слово format добавляет проверку распространенных форматов строк вроде email без необходимости писать регулярное выражение самостоятельно.
Автоматически сгенерированная схема — хороший черновик для начала, но список required и конкретные ограничения обычно требуют ручной доводки под реальную бизнес-логику.