Валидатор JSON Schema

Что такое инструмент JSON Schema?#

Сам по себе JSON-значение говорит, чем данные являются — тут строка, там число. Но он не говорит, чем данные должны быть: должно ли age быть неотрицательным целым, обязательно ли email, разрешено ли tags быть пустым. JSON Schema — словарь для таких утверждений. Вы пишете схему — небольшой JSON-документ, описывающий форму, — а валидатор проверяет, подходит ли кусок данных под эту форму, поле за полем.

Эта страница делает две задачи одним движком схем. Проверить берёт схему и документ данных и точно сообщает, какие поля нарушают какие правила, каждое с привязкой к его пути в документе. Вывести идёт в обратную сторону: дайте ему образец JSON-значения, и он напишет за вас схему в стиле Draft-07, обходя структуру и фиксируя тип каждого поля. Оба направления естественно компонуются: вывести схему из типичного образца, а затем проверять каждый будущий документ по ней.

Валидация работает на том же движке Ajv, что и продакшен-код, с тремя доступными драфтами (Draft-07, 2019-09, 2020-12) и ослабленной строгой защитой, поэтому слегка нестрогая схема допускается, а не отвергается с порога.

Как пользоваться#

1. Выберите режим переключателем на панели инструментов:
   • Проверить (по умолчанию): вставьте схему слева, данные справа.
   • Вывести: вставьте образец JSON-значения слева, прочитайте сгенерированную схему справа.
2. В режиме Проверить выберите Draft, под который написана схема, — Draft-07 покрывает подавляющее большинство существующих схем; выбирайте 2019-09 или 2020-12, только если схема использует возможности, введённые этими драфтами.
3. Выберите Отступ для вывода — 2 или 4 пробела. В режиме «Вывести» это управляет форматированием сгенерированной схемы.
4. Правая панель показывает либо документ данных (Проверить), либо выведенную схему (Вывести). Метки панелей меняются в соответствии с режимом.
5. В режиме Проверить панель Нарушения под панелями перечисляет каждое нарушение как путь — причина. Корень документа показан как (root); вложенное поле — своим JSON Pointer, например /age.
6. Нажмите Копировать на правой панели, чтобы забрать выведенную схему или данные, либо Пример / Очистить, чтобы загрузить или сбросить.

Результат вычисляется, как только оба ввода разбираются. Ошибка синтаксиса схемы или данных сообщается с точной строкой и столбцом и помечается как проблема схемы, данных или компиляции, чтобы вы знали, куда смотреть.

Ключевые возможности#

• Два режима, один движок. Проверка документов или генерация схемы из образца — на одном доверенном валидаторе.
• Три драфта. Draft-07, 2019-09 и 2020-12 грузят только свой собственный скомпилированный валидатор, поэтому вы всегда проверяете против того драфта, который реально целитесь.
• Все ошибки, а не только первая. Каждое нарушение собирается, поэтому документ с пятью проблемами показывает пять проблем вместо пяти проходов туда-обратно.
• Нарушения с привязкой к пути. Каждое нарушение указывает на своё место в документе — (root) для проблем всего документа или точный указатель вроде /user/address/zip.
• Строгий режим ослаблен. Схема с неизвестным ключевым словом или отсутствующим типом верхнего уровня допускается и выполняется, а не отвергается при компиляции — правильное поведение для инструмента, чья работа — проверять, а не поучать.
• Только локально. Схемы и данные обрабатываются в вашем браузере. Ничего не загружается.

Разбор примера#

Объект user обязан иметь name, а age должен быть неотрицательным целым. Вставьте эту схему слева в режиме Проверить:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}

Теперь проверьте документ, нарушающий оба правила, — без name и с отрицательным age:

{
  "age": -3
}

Панель «Нарушения» сообщает о двух нарушениях, каждое с привязкой к месту:

(root) — must have required property 'name'
/age   — must be >= 0

Путь (root) говорит, что отсутствующее обязательное свойство — проблема уровня документа; /age указывает прямо на виновное поле. Исправьте данные на {"name":"ada","age":36}, и статус переключится на «допустимо» с пустым списком нарушений. Текст причины — собственные формулировки Ajv для каждого ключевого слова, сохранённые дословно, поэтому они совпадают с тем, что будут писать ваши продакшен-логи.

FAQ#

Draft-07, 2019-09 или 2020-12 — что выбрать?#

Draft-07 — прагматичный выбор по умолчанию: подавляющее большинство схем в туториалах, библиотеках и спецификациях OpenAPI нацелены на него, и всё, что вам скорее всего понадобится (type, properties, required, minimum, format, $ref), работает там. Переходите на 2019-09 или 2020-12, только когда схема явно использует возможности, добавленные этими драфтами, — например unevaluatedProperties или пересмотренное поведение $ref. Выбор неправильного драфта обычно всё ещё работает, но безопасный выбор — драфт, задуманный автором схемы.

Почему сообщения о нарушениях на английском?#

Это собственный текст причин Ajv для каждого ключевого слова (must have required property, must be >= 0 и т. д.), переданный без изменений. Смысл в согласованности: это точные строки, которые будут писать ваши серверные валидации в лог, поэтому совпадение здесь делает рассогласование тривиально отслеживаемым в продакшене через grep.

Что значит «строгий режим ослаблен»?#

Строгий режим Ajv отвергает схемы, которые он считает небрежными, — неизвестное ключевое слово, $ref, который он не может разрешить, отсутствующий type. Это полезно в пайплайне сборки, но неправильно для инструмента-валидатора, чья работа — проверять данные против любой схемы, которую вы ему дадите. Эта страница отключает строгий режим, поэтому нестрогая схема компилируется и выполняется, а не выбрасывает ошибку.

Можно ли вывести схему, а затем проверять по ней?#

Да — именно такой обратный путь и задуман. Вставьте типичный образец в режим Вывести, скопируйте сгенерированную схему, переключитесь на Проверить и вставьте схему обратно слева. Выведенная схема чисто перепроверяет исходный образец, а далее вы можете проверять по ней каждый новый документ.