Проверка YAML по JSON Schema

Как проверить конфигурацию YAML (CI, Kubernetes, настройки сервиса) по JSON Schema и увидеть ошибки в строках документа.

Большинство схем конфигураций публикуется как JSON Schema, а сами конфигурации пишут в YAML. Проверить одно по другому можно прямо в редакторе YAML — ошибки окажутся в тех строках, где их нужно исправить.

Как проверить

Откройте документ в редакторе YAML.
Справа выберите вкладку Проверка по схеме.
Выберите JSON Schema из своих артефактов (после входа) или нажмите Загрузить схему — файл .json или .yaml.
Нажмите Проверить: на вкладке появится итог и список ошибок, а в строках документа — подчёркивание и сообщение на русском при наведении.

Ошибки проверки YAML по схеме в строках документа — Ошибки проверки по схеме привязаны к строкам YAML

Как это работает

Документ YAML читается в ту же структуру, что и JSON (с раскрытием якорей), и проверяется по схеме. Путь ошибки, например /jobs/build/steps/0, переводится обратно в номер строки YAML-документа. Поддерживаются схемы draft-07 и 2020-12.

Где взять схему

Схемы популярных форматов (GitHub Actions, GitLab CI, docker-compose, OpenAPI) публикуются в каталоге SchemaStore — скачайте файл и загрузите его на вкладке проверки.
Свою схему можно вывести из примера («Генерация JSON Schema из JSON») и доработать в редакторе JSON Schema.
Схему, которой пользуется команда, удобно держать в проекте рядом с конфигурациями — тогда её не надо загружать каждый раз.

Типичные находки

Опечатка в имени ключа — при additionalProperties: false это ошибка «недопустимое поле».
Значение не того типа: replicas: "3" вместо числа.
Ключ на неправильном уровне вложенности из-за отступа — схема сообщит об отсутствующем обязательном поле там, где ключ должен был быть.

Пример: конфигурация сервиса

Схема требует name, число replicas от 1 до 10 и ограничивает env значениями dev/test/prod. Документ

name: orders
replicas: "3"
env: stage
retries: 3

получит ошибки: replicas — строка вместо числа (кавычки), env — значение не из перечисления, а при additionalProperties: false — недопустимое поле retries. Каждая ошибка — в своей строке.

Вопросы и ответы

Нужно ли переводить YAML в JSON для проверки? Нет, проверка идёт прямо по YAML; перевод выполняется внутри, а ошибки возвращаются к строкам YAML.

Схема в YAML — подойдёт? Да: «Загрузить схему» принимает файлы .json, .yaml и .yml.

Якоря и слияние ключей учитываются? Да: схема проверяет документ после раскрытия якорей — так, как его увидит программа.