Основные выводы
- 01Powered by Ajv, наиболее широко используемый JavaScript JSON Schema валидатор — то, что проходит здесь, проходит в Node.js, Fastify и большинстве JS инструментных цепей.
- 02Сообщает каждую ошибку проверки сразу (режим allErrors), а не только первый сбой.
- 03Каждая ошибка включает путь указателя JSON к неправильному полю для быстрой навигации.
- 04Обе схемы и данные работают полностью в вашем браузере — ничего не загружается.
Почему проверять JSON против схемы?
JSON Schema — это стандартный способ описания формы документа JSON — требуемые поля, допустимые типы, ограничения значений, структуры вложенных объектов. Проверка против схемы перед достижением полезной нагрузки производства ловит несоответствия типов, пропущенные требуемые поля и нарушения ограничений рано, когда они дешевы для исправления.
Наиболее распространенные случаи использования — тестирование тел запросов и ответов API, проверка файлов конфигурации, проверка примеров объектов OpenAPI и проверка экспортов данных против известной структуры. Валидатор Handytool использует Ajv — де-факто JavaScript библиотека JSON Schema, используемая внутри самого Node.js — поэтому результаты здесь совпадают с тем, что ваш бэк-энд увидит.
Как проверять JSON против схемы
- 01
Вставьте ваш JSON Schema
Вставьте схему в левую панель. Это может быть Draft 7 или 2019-09 или 2020-12 схема с type, properties, required, items, anyOf, allOf — любое стандартное ключевое слово Ajv.
- 02
Вставьте ваши JSON данные
Вставьте документ данных, который вы хотите проверить, на правую панель. Это экземпляр — тело запроса API, объект конфигурации, запись экспорта или один пример из вашей спецификации OpenAPI.
- 03
Нажмите Validate
Ajv запускает проверку с allErrors: true, означающей, что она собирает каждый сбой, а не останавливается на первом.
- 04
Просмотрите список ошибок
Каждая ошибка показывает путь указателя JSON к неправильному значению (например /user/email), неправильное ключевое слово (type, required, minimum) и человеческое читаемое сообщение. Исправьте каждое и переопроверьте.
Что разработчики проверяют с JSON Schema
- 01REST API тела запросов — подтвердите полезную нагрузку совпадает с формой ожидаемой конечной точкой перед отправкой.
- 02Примеры объектов спецификации OpenAPI — проверьте каждый пример против встроенной схемы компонента.
- 03Файлы конфигурации — обеспечьте требуемые ключи присутствуют и значения правильного типа.
- 04Записи конвейера данных — место структурной путаницы между производителями и потребителями данных.
- 05Полезные нагрузки представления формы — тест, что проверка фронт-энда зеркалирует ограничения схемы бэк-энда.
- 06Тела веб-перехватчика третьего лица — подтвердите документируемая схема совпадает с фактической полезной нагрузкой.
Приватная проверка, сервер не требуется
Ajv работает полностью в вашем браузере. Ни схема, ни данные не отправляются на какой-либо сервер — вы можете безопасно проверять схемы, которые описывают внутренние структуры данных и объекты данных, которые содержат чувствительные значения полей.
Валидатор поддерживает черновики JSON Schema 6, 7, 2019-09 и 2020-12. Наиболее распространенный черновик в дикой природе — Draft 7, который охватывает все ежедневные ключевые слова: type, properties, required, items, minimum, maximum, pattern, enum, anyOf, allOf, oneOf, not и $ref.
Часто задаваемые вопросы о валидаторе JSON Schema
Какие черновики JSON Schema поддерживаются?
Ajv поддерживает черновики 6, 7, 2019-09 и 2020-12. Draft 7 наиболее распространен в существующих базах кода и охватывает все стандартные ключевые слова.
Почему моя $ref схема не разрешается?
Внешние URL-адреса $ref не возьмутся в этом инструменте только для браузера. Встраивайте все ссылочные схемы, используя $defs и локальные указатели JSON типа #/$defs/MyType.
Загружается ли моя схема или данные на какой-либо сервер?
Нет. Ajv работает полностью в вашем браузере — обе схемы и данные остаются на вашем устройстве.
Могу ли я использовать это для проверки спецификации OpenAPI 3?
Вы можете проверить компоненты отдельной схемы и примеры объектов. Проверка всего документа OpenAPI требует отдельного валидатора OpenAPI, который понимает спецификацию мета-схемы.
Почему я вижу несколько ошибок вместо просто первой?
Валидатор сконфигурирован с allErrors: true, что заставляет Ajv собирать каждый сбой, а не останавливается на первом. Это намеренное — вы можете исправить все проблемы в одном проходе, а не делать повторные попытки проверки.