JSON Toolkit

Валидация YAML через JSON Schema: страховка для конфигурационных файлов

Главное: YAML-файл, который парсится без ошибок, не является правильным файлом: country: NO — не строка для парсера YAML 1.1, а version: 1.10 молча превращается в число 1.1. Это руководство объясняет, почему JSON Schema может валидировать YAML, рабочие CLI- и редакторские способы настройки, как схема поймала бы реальный инцидент с норвежским кодом страны, и три ограничения валидации по схеме.

Средний~6 мин чтенияОпубликовано 2026-11-13Обновлено 2026-11-13
Схема, иллюстрирующая валидацию YAML-конфигурационных файлов через JSON Schema

Вывод: YAML 1.2 — это строгое надмножество JSON, поэтому JSON Schema валидирует структуру данных после парсинга, а не формат файла — напишите схему один раз, и она покроет и JSON-, и YAML-данные. Именно поэтому она способна перехватить инциденты, когда парсер молча меняет тип.

yaml.safe_load без ошибок доказывает лишь то, что файл — легальный YAML. Он не доказывает, что country: NO всё ещё строка — под парсером YAML 1.1 это уже false задолго до того, как ваш код увидит файл.

Один: парсинг без ошибок ≠ корректная конфигурация — сначала реальный инцидент

Команда e-commerce добавила Норвегию в страны доставки: одна строка, NO, в список в group_vars Ansible. Отревьюено, провалидировано, задеплоено. Через неделю — ноль норвежских заказов: JSON-файл на серверах содержал "DK", false, "SE". Ansible парсит файлы переменных через PyYAML, парсер YAML 1.1: NO стал логическим false ещё при чтении файла, а фильтр to_json честно это записал. Шаблон отрендерился, JSON был валиден, никто не жаловался — лишь сервис checkout продолжал отказывать каждому норвежскому клиенту, потому что NO не было в списке.

Общее у таких инцидентов: все синтаксические инструменты зелёные, тогда как слой данных уже неверен. Таблица ниже показывает измеренный на PyYAML 6.0.3 дрейф типов; парсеры YAML 1.2 исправляют лишь часть:

Вы пишете YAML 1.1 читает YAML 1.2 читает Вы хотели
country: NO false "NO" "NO"
version: 1.10 число 1.1 число 1.1 "1.10"
zip: 02134 восьмеричное 1116 десятичное 2134 "02134"
mode: 0755 десятичное 493 десятичное 755 493 или "0755"
ports: ["22:22"] шестидесятеричное 1342 "22:22" "22:22"

Радикальное средство — брать в кавычки любую строку, похожую на код. Но кавычки держатся на человеческой памяти; схема держится на машинной проверке — вот почему YAML заслуживает JSON Schema.

Два: почему JSON Schema может управлять YAML

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

  1. Спарсить YAML-файл в объекты/массивы;
  2. Загрузить JSON Schema;
  3. Провалидировать данные по схеме — ошибки или проход.

Заметьте: шаг один не требует сериализовать YAML в JSON-текст и парсить заново; YAML-библиотека вашего языка передаёт структуру валидатору напрямую. Саму схему тоже можно писать в YAML (yq -P schema.json > schema.yaml — одна команда), но держать её в JSON — самый безопасный выбор: совместимость инструментов лучше, и все схемы каталога schemastore.org — в JSON.

Три: три CLI-способа, которые работают уже сегодня

Возьмём config.yaml, где схема требует name и version, диктует форму semver и countries как массив строк из двух заглавных букв:

# config.yaml
name: checkout
version: "1.4.2"
countries:
  - DK
  - NO
  - SE

Python (jsonschema + PyYAML):

import json, yaml
from jsonschema import validate

data = yaml.safe_load(open("config.yaml", encoding="utf-8"))
schema = json.load(open("schema.json", encoding="utf-8"))
validate(instance=data, schema=schema)

Node (js-yaml + Ajv):

import Ajv from "ajv";
import yaml from "js-yaml";
import fs from "fs";

const schema = JSON.parse(fs.readFileSync("schema.json", "utf8"));
const data = yaml.load(fs.readFileSync("config.yaml", "utf8"));
const validate = new Ajv().compile(schema);
if (!validate(data)) console.error(validate.errors);

Чистый пайплайн (yq + ajv-cli):

yq -o=json config.yaml | ajv validate -s schema.json -d -
# Или check-jsonschema, который принимает YAML напрямую
pip install check-jsonschema
check-jsonschema --schemafile schema.json config.yaml

Три способа отличаются лишь шагом парсинга: первые два явные, в две строки, пайплайн проходит одним потоком, а check-jsonschema делает конверсию YAML→JSON внутри себя. Файл схемы — один и тот же для всех трёх.

Четыре: валидация в реальном времени в редакторе: modeline и SchemaStore

Расширение YAML от Red Hat (на базе yaml-language-server) насчитывает около 30 миллионов установок в VS Code и поддерживает JSON Schema draft-04/07/2019-09/2020-12. Три способа подключить:

# Вариант 1: modeline — первая строка файла указывает на схему
# yaml-language-server: $schema=./schema.json
name: checkout
// Варианты 2 и 3: .vscode/settings.json, по имени файла или glob
{
  "yaml.schemas": {
    "./schema.json": ["config/*.yaml", "*.config.yaml"],
    "https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
  }
}

yaml.schemaStore.enable включён по умолчанию: привычные файлы вроде package.json, GitHub-воркфлоу или docker-compose привязываются к каталогу schemastore.org автоматически, без какой-либо настройки. Поля description схемы становятся подсказками автодополнения и тултипами, а отсутствующие required-свойства подчёркиваются красным — ошибки конфигурации переезжают из «отладки после деплоя» в «момент набора текста». Это объясняет и то, почему SchemaStore, а не «стандарт схем для YAML»: у YAML нет официального стандарта схем, и JSON Schema — стандарт де-факто.

Пять: как схема поймала бы норвежскую проблему

Вернёмся к инциденту с NO из первого раздела. Дадим countries схему на уровне элементов:

{
  "type": "object",
  "required": ["name", "version", "countries"],
  "properties": {
    "countries": {
      "type": "array",
      "items": { "type": "string", "pattern": "^[A-Z]{2}$" }
    }
  }
}

false, произведённый PyYAML, — не строка, поэтому type: string падает мгновенно; даже если бы парсер прочитал это как "no" в нижнем регистре, pattern бы остановил. Для более глубокого контроля добавьте белый список enum. Та же схема крутится в CI через CLI-способы раздела три и в редакторе через modeline раздела четыре — один контракт на обоих концах.

Разделение труда с yamllint стоит предложения: правило truthy yamllint (принимаются только true/false, любое другое логическое написание помечается) управляет стилем написания и ловит flag: yes на уровне линта; JSON Schema управляет формой данных, независимо от парсера. Команда из инцидента в итоге приняла все три: кавычки на строках, yamllint truthy в пайплайне и проверку двухбуквенных строк в шаблоне. Два слоя обороны не перекрываются — они дополняют друг друга.

Шесть: пакетная валидация манифестов Kubernetes

Сам API Kubernetes описан в OpenAPI, и проект kubernetes-json-schema конвертирует его в стандартный JSON Schema. Kubeconform использует этот реестр для пакетной валидации: на ноутбуке с 4 ядрами 35 139 файлов и 50 714 ресурсов с kubeconform -ignore-missing-schemas -n 8 -summary завершаются за 6,7 секунды, против 35 секунд у kubeval на той же задаче. Стандартный приём Helm — сначала рендер, потом валидация:

helm template my-app ./charts/my-app > rendered.yaml
kubeconform -strict -summary -kubernetes-version 1.28.0 rendered.yaml

-strict отбрасывает поля, не определённые схемой (опечатки видны рано); CRD-ресурсы можно пропустить через -ignore-missing-schemas или подключить собственный реестр через -schema-location.

Семь: чего валидация по схеме не может: три ограничения

  1. Дрейф версии парсера происходит на шаге парсинга. Схема видит результат парсинга: NO, прочитанное PyYAML, — уже false, и схема может лишь замкнуть это неверное значение через type/pattern. Радикальное средство остаются кавычки; не ждите от схемы ремонта парсера.
  2. Логические ошибки — за периметром. Опечатка в selector или K8s-selector, указывающий на несуществующий label, — схема знает формы, а не семантику. Это территория admission webhooks, политик OPA или kubectl apply --dry-run=server.
  3. Дубликаты ключей выигрывают молча. Многие YAML-парсеры принимают дубликаты ключей без предупреждения (побеждает последний), так что схема получает данные, где ключ уже потерян. Правило key-duplicates yamllint или хуки парсинга остаются детекторами.

Чеклист перед деплоем: кавычки на строках, похожих на код → запустить yamllint (truthy + key-duplicates) → валидация JSON Schema и в CI, и в редакторе → для кластерных ресурсов дополнительно --dry-run=server. С этими четырьмя шагами норвежский инцидент из раздела один не доживает до второго шага пайплайна.

FAQ

Может ли JSON Schema валидировать YAML-файлы напрямую?

Да — но он валидирует данные, в которые файл парсится, а не сам файл. YAML 1.2 — строгое надмножество JSON, оба парсятся в одни структуры, поэтому одна схема служит и для JSON, и для YAML. Выберите один из четырёх способов — Python, Node, пайплайн yq или check-jsonschema — без ручной конвертации форматов.

Что такое SchemaStore и как им пользоваться?

schemastore.org — это каталог JSON Schema (catalog.json), собирающий схемы сотен распространённых конфиг-файлов: package.json, GitHub-воркфлоу, docker-compose и т. д. Редакторы с поддержкой YAML/JSON автоматически привязывают файлы к каталогу, либо можно сопоставить URL вручную в yaml.schemas. Схему собственного проекта тоже можно подать в каталог.

Дублируют ли yamllint и JSON Schema друг друга?

Нет. yamllint проверяет стиль написания (отступы, длину строк, truthy, дубликаты ключей) на текстовом уровне; JSON Schema проверяет структуру данных (типы, required, enum, pattern) на уровне данных. Список исправлений норвежского инцидента использовал оба: правило truthy ловит написания вроде flag: yes, тогда как схема ловит false, оказавшийся в массиве строк.

Для Kubernetes: kubeconform или kubectl dry-run?

Два разных ремесла. Kubeconform работает офлайн и пакетно, без кластера, его место — CI для структурных ошибок; dry-run=server говорит с настоящим API-сервером и раскрывает проблемы admission webhook и квот, но требует доступа к кластеру. Стандартная комбинация: kubeconform в CI, затем проход --dry-run=server перед деплоем — держите оба слоя.


Написав схему, вставьте JSON, конвертированный из вашего YAML, в онлайн-валидатор JSON, чтобы сначала увидеть ошибки; чтобы писать ключевые слова схемы, смотрите руководство по JSON Schema; чтобы держать схему под контролем тестов в CI, прочитайте контрактное тестирование JSON Schema; для ежедневной конвертации JSON↔YAML используйте конвертер JSON YAML XML.