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

Висновок: 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 без змін. Обидва формати парсяться в одні й ті самі структури даних, тож розширення файлу для валідатора значення не має. Весь пайплайн — три кроки:
- Спарсити YAML-файл в об'єкти/масиви;
- Завантажити JSON Schema;
- Валідувати дані проти схеми — помилки або прохід.
Зауважте: крок один не вимагає серіалізувати 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.
Сім: чого валідація за схемою не може: три обмеження
- Дрейф версії парсера відбувається на кроці парсингу. Схема бачить результат парсингу:
NO, прочитане PyYAML, — ужеfalse, і схема може лише замкнути це хибне значення черезtype/pattern. Радикальний засіб — лапки; не чекайте від схеми ремонту парсера. - Логічні помилки — поза периметром. Одрук у selector або K8s-selector, що вказує на неіснуючий label, — схема знає форми, а не семантику. Це терен admission webhooks, політик OPA або
kubectl apply --dry-run=server. - Дублікати ключів виграють мовчки. Багато YAML-парсерів приймають дублікати ключів без попередження (виграє останній), тож схема отримує дані, де ключ уже втрачено. Правило
key-duplicatesyamllint або хуки парсингу залишаються детекторами.
Чекліст перед деплоєм: лапки на рядках типу коду → запустити 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.