Что такое JSON Schema?

JSON Schema описывает, как должен выглядеть документ JSON: какие свойства есть у объекта, какие из них обязательны, каков тип каждого значения, допустимые диапазоны и длины, шаблоны и форматы, например адреса электронной почты или даты. API, файлы конфигурации и конструкторы форм используют схемы для проверки данных, прежде чем доверять им, а OpenAPI описывает с их помощью тела запросов и ответов.

Как пользоваться валидатором

  1. Вставьте или введите JSON Schema в первое поле.
  2. Вставьте или введите данные JSON для проверки во второе поле.
  3. Результат отображается по мере ввода: либо JSON корректен, либо перечислены все ошибки с путем к некорректному значению, ключевым словом схемы, которому оно не соответствует, и кратким пояснением.
  4. Каждое некорректное значение отмечено в данных. Нажмите на ошибку, чтобы перейти к соответствующему месту в данных, или нажмите на отметку, чтобы найти связанную с ней ошибку в списке.

Поле «Версия схемы» показывает, по какой версии JSON Schema проверялись данные.

Какие версии поддерживаются

Версию схемы выбирает ключевое слово $schema:

  • Черновик 2020-12: https://json-schema.org/draft/2020-12/schema
  • Черновик 2019-09: https://json-schema.org/draft/2019-09/schema
  • Черновик 7: http://json-schema.org/draft-07/schema#
  • Черновик 6: http://json-schema.org/draft-06/schema#

Схема без $schema проверяется как черновик 7. Черновик 4 и более ранние версии не поддерживаются. Сначала схема проверяется по метасхеме соответствующей версии, поэтому опечатка вроде "type": "strin" будет указана как ошибка схемы, а не проигнорирована. Дополнительные аннотации, например title, description и examples, допустимы, как и ключевые слова, неизвестные этой версии, например ваши собственные аннотации x-: они игнорируются.

Как читать ошибки

  • Пути записываются в формате JSONPath, начиная с $ — корня всего документа: $.ingredients[1].unit указывает на свойство unit второго ингредиента.
  • Если обязательное свойство отсутствует, ошибка указывается для объекта, в котором оно должно находиться; в сообщении приводится имя свойства.
  • Если схема не разрешает дополнительное свойство, ошибка указывает на его имя.
  • Для enum и const в сообщении перечислены допустимые значения.
  • Для anyOf и oneOf каждая неудачная ветвь добавляет собственные ошибки, а затем добавляется ошибка для самого ключевого слова, поэтому одно неверное значение может привести к нескольким ошибкам.

Сообщения об ошибках предоставляет библиотека Ajv, и они написаны на английском языке.

Форматы

Также проверяются значения с ключевым словом format: email, uri, uri-reference, date, time, date-time, duration, uuid, ipv4, ipv6, hostname, regex, json-pointer и другие. Неизвестный валидатору формат игнорируется, как это допускает спецификация JSON Schema.

Ссылки

$ref работает для определений внутри той же схемы, например #/$defs/address или #/definitions/address. Ссылки на другие файлы или URL не загружаются: схема, для которой нужна такая ссылка, помечается как недопустимая, а в сообщении указывается ссылка, которую не удалось разрешить.

Как это работает

Инструмент проверяет данные с помощью Ajv — широко используемого валидатора JSON Schema — и проверяет форматы с помощью ajv-formats. Все операции выполняются в браузере: схема и данные никуда не отправляются.

Возможности

  • Поддержка черновиков JSON Schema 6, 7, 2019-09 и 2020-12; версия выбирается по $schema
  • Для каждой ошибки указываются путь, ключевое слово и сообщение
  • Некорректные значения отмечаются в данных; нажатие позволяет перейти к ним
  • Проверка форматов адресов электронной почты, URI, дат, UUID, IP-адресов и других
  • Проверка схемы по метасхеме
  • Указание строки и столбца для синтаксических ошибок JSON
  • Работа в браузере