Как пользоваться: Валидатор JSON Schema
- Вставьте JSON Schema слева, а проверяемый JSON справа (YAML тоже подойдёт).
- Драфт определяется по полю
$schema, или вы можете выбрать его вручную. - Изучите список ошибок: расположение в JSON, описание проблемы и правило схемы, которое не выполнилось.
- Нет схемы? Вставьте пример данных и нажмите Сгенерировать схему из данных.
Что такое JSON Schema?
JSON Schema — это словарь для описания структуры JSON-данных: какие свойства существуют, их типы, какие из них обязательны, допустимые значения, форматы строк, диапазоны чисел и длины массивов. Её используют для проверки запросов и ответов API, конфигурационных файлов, данных из форм и конвейеров обработки данных. На ней также основаны определения запросов и ответов в OpenAPI.
Как читать ошибки
| Колонка | Значение |
|---|---|
| Где | JSON Pointer к значению с ошибкой, например /items/0/qty — поле qty первого элемента |
| Проблема | Что не так: неверный тип, отсутствует обязательное свойство, значение не разрешено, неожиданное свойство… |
| Правило схемы | Путь к ключевому слову в схеме, которое отклонило значение, например #/properties/items/items/properties/qty/minimum |
Драфты
У JSON Schema есть несколько версий. Draft 2020-12 — актуальная (её использует OpenAPI 3.1); draft-07 по-прежнему чаще всего поддерживается библиотеками и редакторами; draft-04 встречается в старых спецификациях, таких как Swagger 2.0 и OpenAPI 3.0. Валидатор читает $schema, чтобы выбрать нужный набор правил. Различия, которые чаще всего сбивают с толку: draft-04 использует id вместо $id и логический exclusiveMinimum; 2019-09 заменил definitions на $defs и добавил unevaluatedProperties.
Частые ошибки
- Забыть
"additionalProperties": false— без него неизвестные свойства разрешены. - Поместить
requiredвнутрь свойства, а не в родительский объект. - Ожидать, что
formatпроверяется везде — многие валидаторы только аннотируют форматы, если их не попросить проверять. - Использовать
"type": "integer"для значений вроде1.0, которые в некоторых языках приходят как дробные числа.
Сгенерированные схемы — это отправная точка: уточните их с помощью шаблонов, enum и ограничений. Изучайте большие документы в просмотрщике JSON или создавайте типы TypeScript с помощью JSON to TypeScript. Проверяете спецификацию API? Воспользуйтесь валидатором OpenAPI.
Также ищут как: json schema validator online, ajv онлайн, json schema draft 2020-12, json в json schema, валидация json по схеме.
Инструменты, которые хорошо сочетаются с Валидатор JSON Schema
- JSON в JSON Schema — Вставьте один или несколько примеров JSON, и вы получите JSON Schema, которая их описывает: вложенные объекты, массивы объектов, объединённые в одну схему элемента, обязательные поля (ключи, присутствующие во всех примерах), распознанные форматы вроде email, date-time, URI и UUID, необязательные enum и вывод в формате 2020-12 или draft-07.
- JSON форматтер — Вставьте JSON, чтобы отформатировать, минифицировать или проверить его.
- Валидатор YAML — Вставьте файл Docker Compose, манифест Kubernetes, workflow GitHub Actions или любой YAML, чтобы найти ошибку, поймать типичные ловушки и получить аккуратно отформатированную версию.
- Тестер JSONPath — Введите запрос JSONPath и сразу увидите, что он выбирает, с точным путём каждого совпадения.
Часто задаваемые вопросы
Какой валидатор JSON Schema используется здесь?
Можно ли сгенерировать JSON Schema из JSON?
Поддерживается ли $ref на другие файлы?
#/$defs/...) работают. Внешние URL не загружаются, поэтому сначала вставьте эти определения прямо в схему.