Как проверить структуру JSON по JSON Schema

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

В валидаторе JSON Schema Neraviko вводятся два текста: проверяемый JSON и схема. Инструмент работает с ограниченным подмножеством Draft 2020-12. Поэтому схему для другой версии или с любыми произвольными расширениями нельзя считать совместимой заранее. Сам стандарт и границы конкретного сервиса следует проверять отдельно. Спецификация JSON Schema 2020-12.

Пример: объект с идентификатором и количеством

Данные ниже синтетические. Они описывают учебную позицию, не настоящий заказ:

{"id":"DEMO-17","quantity":2}

Схема для поля схемы:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "quantity"],
  "properties": {
    "id": {"type": "string", "minLength": 1},
    "quantity": {"type": "integer", "minimum": 1}
  }
}

В этой задаче нужен объект с двумя обязательными свойствами. Идентификатор должен быть непустой строкой, количество — целым числом не меньше единицы. Другие свойства этот учебный контракт не запрещает. Важно записать required отдельно: перечисление в properties само по себе не делает поле обязательным. Официальное руководство JSON Schema: свойства объекта.

Показанный корректный объект дал output.valid=true и статус success при проверке действующего сервиса 05.10.2026. Этот результат относится к показанному синтетическому примеру и указанной схеме.

Проверяем ошибку типа

Теперь оставьте схему прежней и замените данные:

{"id":"DEMO-17","quantity":"2"}

У строки "2" и числа 2 разный тип. При live-проверке 05.10.2026 получен output.valid=false со статусом needs_review. Нарушение SCHEMA_TYPE относится к правилу type для quantity: instance_path равен /quantity, schema_path — /properties/quantity/type.

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

Неудачное соответствие схеме — завершённая проверка. Neraviko описывает его статусом needs_review и HTTP 200. Ошибка самого ввода, некорректная или неподдерживаемая схема возвращаются через error envelope с HTTP 422. Поэтому один код HTTP 200 не означает, что документ подходит: смотрите valid и нарушения.

Порядок работы в форме

1. Возьмите схему из актуального контракта интеграции. Для эксперимента можно начать с учебной схемы выше.
2. Вставьте проверяемый JSON в поле данных, а схему — в поле схемы. Схема тоже должна быть корректным JSON.
3. Выберите предел числа ошибок. По умолчанию Neraviko возвращает до 10; доступен диапазон от 1 до 20.
4. Запустите проверку. Если есть нарушения, сравните путь данных с путём правила.
5. Исправляйте источник документа или согласованную схему и повторяйте проверку до результата, который соответствует вашему контракту.

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

Что поддерживает этот инструмент

В версии v1 доступны типы, числовые ограничения, длины строк, свойства и обязательные поля объектов, элементы массивов, условия и ограниченные композиции схем. Поддерживаются локальные определения и некоторые локальные ссылки через JSON Pointer. Удалённые ссылки, рекурсивные ссылки, цепочки ссылок и ссылки на неподдерживаемые якоря отклоняются. Валидатор не скачивает документы по URL, указанному пользователем.

Ограничения также касаются сложности: схема содержит не больше 512 значений и имеет глубину не больше 24; для данных — до 10 000 значений, глубина 32 и до 1 000 элементов в одном объекте или массиве. Шаблоны pattern ограничены 256 байтами; группы, lookaround, обратные ссылки и possessive quantifiers не допускаются. Для большого контракта сначала проверьте совместимость, затем выберите подходящий валидатор в своей среде.

Исходный текст данных ограничен 262 144 байтами, схемы — 65 536 байтами; действуют и общие ограничения запроса. Перед проверкой схемы Neraviko отклоняет повторяющиеся ключи и числовые записи, которые нельзя безопасно декодировать в пределах его требований совместимости. Поэтому документ, успешно прошедший простую синтаксическую проверку, может быть отклонён на этом этапе.

Что схема не заменяет

Успех доказывает соответствие только переданной схеме. Если схема не требует нужное поле, отсутствие этого поля не станет ошибкой. Валидатор не проверяет существование записи в вашей базе, доступность товара или полномочия пользователя. Такие проверки принадлежат приложению.

И данные, и схема отправляются на сервер Neraviko. Не вставляйте секреты или реальные персональные сведения для учебного эксперимента. Сохраните синтетический корректный и некорректный пример рядом с контрактом: они помогут проверять изменения схемы без клиентских данных.