JSON Schema Validator

Что такое JSON Schema и почему это важно?

JSON (JavaScript Object Notation) — это lingua franca веб-API, конфигурационных файлов и обмена данными. Но у сырого JSON нет встроенной системы типов: поле может быть строкой сегодня и числом завтра, а единственный способ обнаружить несоответствие — это сбой во время выполнения или скрытый баг в данных. JSON Schema заполняет этот пробел: это декларативный словарь для описания ожидаемой структуры и ограничений JSON-документа, который проверяется против реальных данных во время выполнения.

Команды используют JSON Schema для проверки полезных нагрузок запросов API перед их обработкой, для соблюдения структуры конфигурационных файлов при запуске, для автоматической генерации документации и UI-форм из единого источника истины и для поддержания согласованности контрактов между микросервисами. OpenAPI — стандарт документирования REST API — построен прямо на JSON Schema, что делает его наиболее широко используемым стандартом валидации данных в сети.

Версии черновиков JSON Schema: Draft-07, Draft 2019-09 и Draft 2020-12

JSON Schema прошёл через несколько версий спецификаций. Draft-07, выпущенный в 2018 году, по-прежнему является наиболее широко поддерживаемым во всех основных библиотеках валидаторов и используется OpenAPI 3.0. Он ввёл мощные ключевые слова условной валидации if/then/else, аннотации свойств readOnly/writeOnly и ключевые слова кодирования содержимого. Если вы пишете схемы сегодня и не нуждаетесь в новейших функциях, Draft-07 — самый безопасный выбор для максимальной совместимости с экосистемой.

Draft 2020-12 — это текущая стабильная спецификация, которая вносит несколько существенных изменений: ключевое слово items заменяется на prefixItems для проверки кортежей, динамические ссылки используют $dynamicRef вместо $recursiveRef, а новые ключевые слова unevaluatedProperties и unevaluatedItems обеспечивают более точный контроль над дополнительным содержимым.

Основные ключевые слова JSON Schema с объяснениями

Ключевое слово type обеспечивает тип данных: string, number, integer, boolean, array, object или null. required перечисляет свойства, которые должны присутствовать в объекте. properties сопоставляет каждое имя свойства с его собственной субсхемой. pattern применяет регулярное выражение к строковому значению. minimum, maximum, minLength и maxLength ограничивают числовые диапазоны и диапазоны строк. enum ограничивает значение фиксированным набором допустимых значений; const ограничивает его одним значением.

Ключевые слова композиции позволяют строить сложные правила из простых строительных блоков: allOf работает как логическое И, anyOf — как ИЛИ, а oneOf — как исключающее ИЛИ. Ключевое слово not инвертирует схему. Ключевые слова if/then/else обеспечивают условную валидацию. Вместе они позволяют выразить практически любое правило валидации без написания пользовательского императивного кода.

JSON Schema в продакшне: API-контракты и CI-пайплайны

В производственных системах валидация JSON Schema выполняется на стороне сервера или в CI-пайплайнах с использованием библиотек, таких как Ajv (JavaScript/Node.js), jsonschema (Python) или Newtonsoft.Json (C#). Схемы фиксируются в системе контроля версий вместе с кодом приложения, чтобы изменения контракта проверялись и отслеживались как любое другое изменение. Критические изменения — удаление обязательного поля, сужение типа — выявляются при проверке кода до того, как они попадут в продакшн.

Этот браузерный инструмент идеально подходит для итеративной разработки и отладки схем перед их фиксацией. Вставьте данные, напишите схему, нажмите «Проверить», прочитайте подробные сообщения об ошибках и уточните — без сервера, без npm install, без лишних запросов. Валидатор также форматирует ваш JSON при каждом запуске проверки, что делает его удобным комбинированным форматировщиком JSON и тестером схем.

Практический пример: Валидация ответа API

Предположим, ваш API возвращает объект пользователя. JSON Schema, проверяющая его, может требовать целочисленный id, непустое строковое имя, строковый email, соответствующий шаблону email, и необязательную строковую роль из перечисления 'admin', 'editor' и 'viewer'. Установка additionalProperties в false гарантирует, что ваш API никогда не вернёт незадокументированные поля, от которых потребители могут случайно зависеть.

Функция if/then/else позволяет задавать условные правила — например, если роль 'admin', то требуется массив разрешений, иначе он запрещён. Эти составные правила позволяют одной схеме охватывать несколько допустимых форм объекта без дублирования определений свойств.

Как UtiloKit сравнивается с другими валидаторами JSON Schema

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

jsonschemavalidator.net, построенный на библиотеке Microsoft Newtonsoft.Json, сообщает об ошибках с путями свойств .NET и кодами ошибок, которые незнакомы JavaScript-разработчикам. Инструменты вроде Stoplight и SwaggerHub проверяют схемы в рамках полного документа OpenAPI и требуют настройки проекта и аккаунта.

Валидатор UtiloKit работает на том же движке Ajv, который используется в большинстве приложений Node.js, Express и Fastify. Сообщения об ошибках, пути JSON-указателей и поведение ключевых слов точно соответствуют вашей производственной среде — и он работает бесплатно в вашем браузере без аккаунта, загрузки файлов, ограничения размера файла и ежедневного лимита использования.