JSON-руководство

Что такое JSON Schema? Использование, примеры и полное руководство (2026)

Имя автора Опубликовано 2026-08-24 Обновлено 2026-08-24 Около 12 мин чтения

При работе с ответами API или конфигами синтаксически корректный JSON не означает «легальные» данные — пропущенные поля, неверные типы или выход за диапазон часто проявляются только в runtime. JSON Schema создан именно для таких случаев. От определения и сценариев статья переходит к базовому синтаксису, ключевым словам, практическому workflow и выбору инструментов — чтобы вы построили рабочую схему ограничений JSON.

Краткий обзор

Пункт	Описание
Ключевая проблема	JSON синтаксически верен, но структура или значения не по бизнес-правилам
Подход	Schema: типы, обязательные поля, ограничения — автоматическая валидация
Рекомендуемая версия	Draft 2020-12 (наиболее зрелая экосистема)
Статья охватывает	Определение → синтаксис → ключевые слова → практика → выбор → FAQ

Что такое JSON Schema?

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

Сама Schema — валидный JSON-документ, но с другой семантикой: не бизнес-данные, а форма данных. OpenAPI 3.x описывает тела запросов/ответов через JSON Schema; CLI проверяют конфиги; frontend-формы часто валидируют по Schema. Одна Schema — frontend, backend, CI — меньше дублирования валидации на каждом слое.

Зачем нужен JSON Schema?

В повседневной разработке JSON.parse() лишь проверяет скобки и кавычки. Синтаксическая проверка бессильна, когда:

API требует поле email, в ответе его нет
age — integer, клиент прислал строку "25"
Enum status получил "unknown"
Вложенный address.zip не соответствует формату индекса

Ценность JSON Schema — превращение «неявных договорённостей» в исполняемые, общие, версионируемые декларации. Code Review по Schema вместо сюрпризов на интеграции или после релиза.

Основы JSON Schema и примеры

Минимальная Schema объявляет $schema (версия) и корневой type. Ниже объект пользователя: name — обязательная строка; age — необязательное неотрицательное целое.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/user.json",
  "title": "User",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Полное имя пользователя"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["name"],
  "additionalProperties": false
}

Допустимый экземпляр данных:

{ "name": "John Doe", "age": 28, "email": "john@example.com" }

При { "age": 28 } (нет name) или { "name": "Jane Doe", "extra": true } (additionalProperties: false запрещает лишние поля) валидатор вернёт путь и причину ошибки.

Шпаргалка по ключевым словам

В Draft 2020-12 чаще всего используют:

Ключевое слово	Назначение	Пример
type	Объявление типа данных	"string" / "integer" / "object"
properties	Свойства объекта	{ "id": { "type": "integer" } }
required	Список обязательных полей	["id", "name"]
enum	Ограничение enum	["draft", "published"]
format	Распространённые string format	"email" / "date-time"
$ref	Ссылки на другие фрагменты Schema	"#/$defs/Address"

Сложные Schema разбивайте через $defs (Address, Pagination) и $ref — без раздувания одного файла.

JSON Schema и синтаксическая проверка JSON

Разные уровни проблем; на практике обычно вместе:

Синтаксис: скобки, кавычки, запятые → JSON.parse
Schema: поля, типы, ограничения → бизнес-правила

Workflow: сырой текст в JSONSort — форматирование и синтаксис; затем ajv, fastjsonschema — Schema. Синтаксис локально, семантика в Schema.

Практика: workflow валидации API-контракта

Типичный REST-проект — четыре шага:

Schema: schemas/user.json в репозитории, версия с OpenAPI.
Примеры: один валидный и один невалидный — fixtures для unit-тестов.
CI: в PR mock-ответы vs Schema — без случайного удаления полей.
Runtime: Schema на теле запроса, 400 со structured errors, не грязные данные в БД.

Главный выигрыш — видимость изменений: правки полей ловятся в CI, а не случайно на интеграции.

JSON Schema и альтернативные подходы

Подход	Плюсы	Ограничения
JSON Schema	Независимость от языка, нативная поддержка OpenAPI, зрелая экосистема	Ограниченная выразительность для сложных правил; есть кривая обучения
Типы TypeScript	Отличный опыт в IDE, проверка на этапе компиляции	Только экосистема TS; для runtime нужна дополнительная конвертация
Ручная валидация if/else	Гибко, без лишних зависимостей	Сложно поддерживать и переиспользовать, легко пропустить граничные случаи
Protobuf / Avro	Строгая типизация, высокопроизводительная сериализация	Требует шага компиляции; не идеально для чистых JSON API

API уже JSON + OpenAPI — JSON Schema обычно с наименьшим трением; full-stack TypeScript без кросс-языкового контракта — TS в приоритете, Schema дополнительно.

Стоит ли инвестировать в JSON Schema?

Сценарии, куда стоит вкладываться:

Публичное API с machine-readable контрактом для потребителей
Сложные конфиги — перехват ошибок формата до deploy
Web / mobile / backend на одних ограничениях данных
CI на breaking change API

Можно отложить:

Иногда форматировать JSON → достаточно JSONSort
Простая стабильная структура → ручная валидация дешевле
Нет OpenAPI / contract testing → сначала документация, потом Schema

FAQ

Что такое JSON Schema?

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

Чем JSON Schema отличается от JSON?

JSON — данные; JSON Schema — как они должны выглядеть. Аналогия: JSON — «экземпляр», Schema — «форма».

Какую версию выбрать?

Новые проекты — Draft 2020-12. Draft-07 / 2019-09 — не мигрируйте без нужды в новых ключевых словах.

Как валидировать локально?

Синтаксис — JSONSort; Schema — ajv (Node.js), jsonschema (Python) или JSON Schema в VS Code.

Как связаны OpenAPI и JSON Schema?

OpenAPI 3.x — подмножество JSON Schema с расширениями. OpenAPI docs = Schema.

Заключение

JSON Schema не про «parsится ли JSON», а про «соответствует ли договорённостям команды». От определения до CI — неявные правила становятся явным исполняемым контрактом. Начните с малого API или конфига, первая Schema и валидация — затем масштабирование.

Дополнительное чтение

Официальная спецификация JSON Schema Ключевые слова и версии
JSONSort — локальный JSON toolbox Format, syntax check, Diff — локально в браузере
Все статьи блога Больше JSON-туториалов и практики

Changelog: 2026-08-24 первая публикация