Как проверить JSON по JSON Schema и найти ошибки в структуре данных

Что проверяет инструмент

Проверка JSON по JSON Schema помогает понять, соответствует ли текст данных заранее описанной структуре. Это удобно перед передачей объекта между сервисами, при подготовке тестовых данных или при разборе ответа API: отдельно задаётся JSON с данными и отдельно JSON Schema с правилами для этих данных.

Инструмент принимает оба значения именно как текст. Схема может описывать типы строк, чисел, целых чисел, логических значений, объектов и массивов. Для вложенных объектов и массивов проверки выполняются рекурсивно, поэтому можно проверять не только плоский объект, но и структуру с несколькими уровнями.

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

Как выполнить проверку

1. Подготовьте JSON с проверяемыми данными. Например, для записи о товаре можно использовать объект с полями name и count. Проверьте, что текст задуман как JSON: имена свойств должны быть заключены в двойные кавычки, а строковые значения нельзя оформлять одинарными кавычками.

2. Подготовьте JSON Schema для той же структуры. В ней укажите тип корневого значения и правила для нужных свойств. Например, name можно объявить строкой, а count - целым числом с минимальным значением. Если свойство должно присутствовать, добавьте его в список обязательных свойств. Когда схема запрещает дополнительные свойства, объект с полем, которого нет среди объявленных, не пройдёт такую проверку.

3. Вставьте текст данных в поле для JSON и текст схемы в поле для JSON Schema. Оба поля необязательны на уровне формы, но для содержательной проверки нужны оба: если одно из них пустое или состоит только из пробелов, результат сообщает, что данные невалидны, и указывает на отсутствие JSON или схемы.

4. Запустите проверку. Сначала оба текста разбираются как JSON, а затем данные сопоставляются со схемой. Если синтаксически неверен хотя бы один текст, вы получите результат «невалидно» с описанием ошибки разбора, а не обычный отчёт о несоответствии правилам схемы.

5. Изучите сведения о проверке. Сопоставьте указанное поле, тип или ограничение с исходным JSON и при необходимости исправьте либо данные, либо схему. Для массива проверьте правило items: элементы проверяются по объектной схеме, а для не объектной коллекции используется первая схема, если она есть. Пустая не объектная коллекция схем для элементов может сама привести к ошибке проверки.

Как читать результат

Статус «валидно» означает, что переданные данные прошли применённые проверки этой схемы. Это не означает, что структура подходит для любой другой схемы или что в документе проверены возможности, которых инструмент не заявляет. Если результат «невалидно», сначала определите, к какому этапу относится описание: к разбору текста или к проверке уже разобранного JSON.

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

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

Практический пример

Разработчик проверяет объект товара перед передачей его в другой сервис и хочет убедиться, что количество не ниже заданного минимума.

Вставьте объект с полями name и count, где count имеет отрицательное целое значение, а в схеме задайте для него минимальное значение. Запустите проверку и откройте сведения о результате.

Результат содержит признак валидности и сведения о проверке; при несоответствии в них указывается описание применимой проблемы.

Ограничения

• Результат отражает проверки, реализованные для переданной схемы, а не подтверждает поддержку всех возможностей JSON Schema. В частности, по этим правилам нельзя обещать обработку ссылок, композиции, форматов или правил по шаблону.

Частые ошибки

• Причина: в одно из полей вставлен пустой текст, пробелы или синтаксически неверный JSON. Действие: проверьте оба документа отдельно, уберите лишние символы вокруг содержимого и убедитесь, что каждый текст разбирается как JSON до запуска проверки.

Частые вопросы

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

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

Что означает ошибка разбора JSON?

Сначала проверьте синтаксис обоих текстов. Ошибка разбора означает, что JSON не удалось прочитать; при успешно разобранных документах невалидность уже связана с правилами схемы, например с типом, обязательным свойством или ограничением.

Как проверяются массивы и их элементы?

Проверка массивов зависит от правила items. Каждый элемент сопоставляется с объектной схемой, а для не объектной коллекции используется первая схема, если она присутствует; пустая коллекция схем может привести к ошибке проверки.