Валидатор JSON Schema

Что такое валидатор JSON Schema?

// A 5-line schema that catches three real bugs
const schema = {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id":    { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "age":   { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "email"],
  "additionalProperties": false
};

// Three bugs the schema catches:
const bad = { "id": "42", "age": 200 };
//   /id   → type: expected integer, got string
//   /email → required: missing
//   /age   → maximum: 200 > 150

// In Node:        new Ajv().compile(schema)(bad)  // false; ajv.errors has the paths
// In Python:      jsonschema.validate(bad, schema)
// In the browser: this tool — same errors, same paths, no install

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

Примеры

{
  "id": 42,
  "email": "alice@example.com",
  "age": 30
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "email"],
  "additionalProperties": false
}

{
  "id": "42",
  "age": 200
}

{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "maximum": 150 }
  },
  "required": ["id", "email"]
}

{
  "type": "order.created",
  "data": { "orderId": "ORD-001234", "totalUsd": 49.99 }
}

{
  "oneOf": [
    {
      "properties": {
        "type": { "const": "order.created" },
        "data": {
          "type": "object",
          "properties": {
            "orderId": { "type": "string", "pattern": "^ORD-[0-9]{6}$" },
            "totalUsd": { "type": "number", "minimum": 0 }
          },
          "required": ["orderId", "totalUsd"]
        }
      },
      "required": ["type", "data"]
    },
    {
      "properties": {
        "type": { "const": "order.refunded" },
        "data": { "type": "object", "required": ["refundId"] }
      },
      "required": ["type", "data"]
    }
  ]
}

[
  { "sku": "A1", "qty": 3 },
  { "sku": "B2", "qty": 5 },
  { "sku": "A1", "qty": 3 }
]

{
  "type": "array",
  "minItems": 1,
  "uniqueItems": true,
  "items": {
    "type": "object",
    "properties": {
      "sku": { "type": "string", "pattern": "^[A-Z][0-9]+$" },
      "qty": { "type": "integer", "minimum": 1 }
    },
    "required": ["sku", "qty"]
  }
}

Как использовать

1. 1

   Вставьте свою JSON Schema

   Вставьте схему в правое поле. Валидатор автоматически определяет draft по URI $schema, если он есть; иначе выберите Draft 2020-12, 2019-09 или Draft-07 на панели инструментов.

2. 2

   Вставьте свои данные JSON

   Вставьте JSON-документ для проверки в левое поле. Валидация работает по мере ввода; большие входы (>200 КБ) переключаются на ручную кнопку «Валидировать», чтобы ввод оставался отзывчивым.

3. 3

   Прочитайте список ошибок

   Каждая ошибка содержит путь JSON Pointer, keyword и однострочное сообщение. Кликните по ошибке, чтобы перейти к месту в данных, исправьте — и наблюдайте, как счётчик уменьшается в реальном времени.

Типичные ловушки JSON Schema

{ "qty": 1.0 }   schema: { "type": "integer" }   → error: not an integer

{ "qty": 1 }     schema: { "type": "integer" }   → valid

{ "properties": { "name": { "type": "string", "required": true } } }

{ "properties": { "name": { "type": "string" } }, "required": ["name"] }

{ "properties": { "id": { "type": "integer" } } }   accepts: { "id": 1, "foo": "bar", "x": null }

{ "properties": { "id": { "type": "integer" } }, "additionalProperties": false }

{ "type": "string", "nullable": true }   in 2020-12: nullable is just an unknown keyword

{ "type": ["string", "null"] }   in 2020-12: explicitly allows null

pattern: "[A-Z]+"   accepts: "helloX"   (because X matches)

pattern: "^[A-Z]+$"   accepts only: "HELLO"

oneOf: [ { type: "string" }, { type: "string", maxLength: 10 } ]   on: "hi"   → error: matches both

anyOf: [ { type: "string" }, { type: "string", maxLength: 10 } ]   on: "hi"   → valid

Типичные сценарии

Валидация API-запросов

Вставьте тело запроса и схему вашего endpoint перед деплоем. Поймайте ответы 400, которые не покрыли тесты, — пропущенные required, неверные типы, числа вне диапазона.

Проверка payload webhook

Вендор прислал payload, который ваш handler отвергает? Проверьте реальный payload по своей схеме, потом по опубликованной схеме вендора. Diff между ними — ваш баг.

Линтинг файлов конфигурации

package.json, tsconfig.json, helm values.yaml — у каждого файла конфигурации есть публичная схема. Вставьте схему, вставьте конфигурацию, найдите опечатку. Пропустите метод проб и ошибок.

Тестирование компонентов OpenAPI

Вытащите компонент схемы из документа OpenAPI 3.1, вставьте сюда, проверьте примеры payload. Быстрее, чем поднимать mock-сервер; детерминировано, без SDK.

Предварительная проверка отправки формы

Вставьте пример payload формы до того, как подключите валидацию на фронте. Подтвердите, что схема отвергает то, что должна, и принимает то, что должна, потом отправьте ту же схему на клиент и сервер.

Проверка контракта в data-pipeline

ETL-вывод поплыл? Вставьте пример строки и нижестоящую схему. Укажите, какой producer изменился и какие ключи сломались, до того как pipeline переотыграет 10 000 записей.

Технические детали

Соответствие Draft 2020-12

Реализует опубликованную спецификацию Draft 2020-12 — набор keyword, систему типов, словарь format. Перепроверено против вывода Ajv 8.x и ajv-formats.

Пути ошибок в JSON Pointer

Ошибки используют JSON Pointer по RFC 6901 (/user/email/0). Каждое нарушение keyword указывает на единственную разрешимую позицию в данных — без неоднозначности, без поиска по строке.

Разрешение внутренних $ref

Разрешает указатели $ref внутри одного документа (#/$defs/foo, #/properties/bar). Циклы обнаруживаются и сообщаются. Внешние HTTP $ref отключены ради приватности.

Лучшие практики

Всегда задавайте additionalProperties: false

На входных контрактах (тела запросов, файлы конфигурации, сообщения очереди) неизвестные ключи — обычно баги: опечатки, случайные поля или зондирование атакующего. Отвергайте их по умолчанию.

Используйте $defs для переиспользуемых подсхем

Дублируйте одну и ту же форму дважды — и они разойдутся. Перенесите общие определения в $defs и ссылайтесь через $ref — единый источник истины, любое изменение применяется везде.

Валидируйте до бизнес-логики

Запускайте валидацию схемы сразу после JSON.parse, до того как трогать разобранную структуру. Сужение типов, проставление значений по умолчанию и сохранение полагаются на то, что контракт держится — убедитесь, что это так.

Часто задаваемые вопросы