YAML

YAML — это язык сериализации данных для записи структурированной информации в человекочитаемом виде. Обычно используется в файлах с расширениями .yml и .yaml. YAML подходит для конфигураций, описания инфраструктуры и обмена данными между системами, когда важны компактность и читаемость.

Название начиналось как «Yet Another Markup Language», но трактовка закрепилась как «YAML Ain’t Markup Language». Это подчеркивает отличие от разметки: YAML описывает данные, а не внешний вид документа. Формат основан на идее «минимум символов, максимум структуры», поэтому ключевую роль играют отступы и переносы строк.

Где применяют YAML

YAML часто выбирают в задачах DevOps и виртуализации, потому что он удобен для декларативных описаний. Типовые сценарии:

• конфигурации приложений, агентов и сервисов;

• IaC-подход: параметры окружений, ресурсов и связей между ними;

• автоматизация развертывания и управления (пайплайны, джобы, политики);

• описание контейнерных композиций и оркестрации;

• шаблоны параметров для повторяющихся сред (dev/stage/prod).

Файл YAML обычно читается инструментом, который преобразует его в структуры данных (словарь, список, скаляры). Далее эти структуры управляют сборкой, запуском и настройкой компонентов. В большинстве процессов YAML не «выполняется», а интерпретируется как описание желаемого состояния.

YAML, JSON и XML: различия

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

YAML

Ключевые свойства:

• высокая читаемость за счет отступов и малого числа служебных символов;

• поддержка комментариев;

• строки могут быть без кавычек;

• блочный и потоковый стили записи;

• механизмы повторного использования данных (якоря, merge);

• возможность хранить несколько документов в одном файле.

Типичное применение: конфигурации и декларативные описания, которые регулярно читают и правят люди. В синтаксисе допускается запись чистого JSON, что упрощает миграции.

JSON

Ключевые свойства:

• строгий синтаксис и единый стиль записи;

• обязательные кавычки вокруг строк и ключей;

• нет комментариев в стандарте;

• оптимален для сериализации и передачи по HTTP API;

• легко валидируется и обрабатывается в большинстве языков.

Типичное применение: обмен данными между сервисами и клиентами.

XML

Ключевые свойства:

• теговая модель и вложенные элементы;

• атрибуты, пространства имен, схемы и расширенные правила валидации;

• громоздкий формат и низкая компактность;

• удобен для документов со сложной метамоделью и строгими контрактами.

Типичное применение: интеграции, где важны формальные схемы и совместимость со стандартами.

Характерные возможности YAML

Несколько документов в одном файле

YAML допускает хранение набора документов внутри одного файла. Документы разделяются маркером ---; завершение документа можно обозначить ... (используется редко).

env: stage
replicas: 2
...
env: prod
replicas: 6

Комментарии

Комментарий начинается с # и действует до конца строки.

services:
web: nginx # фронтенд
db: postgres # база

Отступы как основа структуры

Иерархия задается пробелами. Табуляция нежелательна. Ошибка в отступе меняет дерево данных, а значит и поведение системы. Для командной работы важны единые правила форматирования и автоматическая проверка.

Повторное использование данных

Якоря и alias-ссылки позволяют вынести общий блок и подключать его в нескольких местах. Это снижает дублирование и риск рассинхронизации параметров.

Явная и неявная типизация

Парсер может вывести тип по значению, либо тип задается явно через тег. Явное указание полезно, когда значение должно остаться строкой.

date_auto: 2023-08-22
date_str: "2023-08-22"
date_typed: !!timestamp 2023-08-22T10:15:00Z

Без встроенного выполнения кода

YAML не содержит механизма запуска команд. Риски обычно связаны с небезопасной десериализацией, когда парсер разрешает произвольные теги и конструирование объектов. В прикладных системах используют безопасные режимы загрузки и ограничивают набор допустимых типов.

Нюансы совместимости и интерпретации

Разные реализации могут по-разному трактовать спорные значения. Частые источники ошибок:

• булевы слова yes/no, on/off в старых режимах могут распознаваться как boolean;

• числа с ведущим нулем могут быть приняты за восьмеричные в некоторых парсерах;

• даты без кавычек могут стать timestamp-типом;

• значение null может задаваться как null, ~ или пустое значение после двоеточия.

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

Синтаксис YAML

YAML оперирует маппингами (словарями), последовательностями (списками) и скалярами (одиночными значениями). Эти три формы комбинируются для построения любых вложенных структур.

Пары «ключ: значение»

Базовая конструкция — ключ и связанное значение. Между ключом и двоеточием пробелы не ставят, после двоеточия обычно ставят один пробел.

app:
name: demo
port: 8080

Скалярные типы

Чаще всего применяются:

• int и float, включая экспоненциальную запись;

• boolean (true/false);

• string;

• null;

• специальные значения (.inf, -.inf, .nan).

Пример:

age: 25
ratio: 1.2e+3
enabled: true
comment: null
pos_inf: .inf

Строки

Строки допускаются без кавычек, но кавычки обязательны при двоеточиях, решетках и ведущих пробелах. Для многострочных значений используют блочные литералы:

• | сохраняет переносы строк;

• > сворачивает переносы в пробелы.

message_raw: |
Первая строка.
Вторая строка.

message_folded: >
Переносы будут
заменены пробелами.

В блоковых строках важны отступы. Блок относится к ключу, пока сохраняется единый уровень отступа.

Последовательности

Список задается через дефисы или в квадратных скобках. Элементы могут быть скалярами или объектами.

ports:
  - 80
  - 443
tags: [edge, public, v1]
users:
  - login: admin
    role: ops
  - login: auditor
    role: audit

Маппинги и вложенные структуры

Маппинг группирует пары ключ-значение. Вложение задается отступами. Один и тот же ключ в пределах маппинга не должен повторяться.

service:
host: example.local
limits:
cpu: "500m"
memory: "256Mi"

Сложные ключи и специальные символы

Ключом может быть строка с пробелами и символами. Тогда используют кавычки. Для коротких структур подходит потоковый стиль.

"complex key":
  value: 10
  inline: {a: 1, b: 2}

Якоря, alias и объединение (merge)

Якорь помечает фрагмент данных, alias-ссылка обращается к нему, а merge (<<) объединяет маппинги.

defaults: &base
retries: 3
timeout: 5s
headers:
X-App: demo

service_a:
<<: *base
url: [https://a.example](https://a.example/)

service_b:
<<: *base
url: [https://b.example](https://b.example/)
retries: 5

Шаблоны конфигураций

В конфигурациях якоря часто играют роль шаблонов. Типовые шаблоны:

• базовые лимиты ресурсов и таймауты;

• общие переменные окружения;

• одинаковые политики логирования;

• наборы меток и аннотаций для сервисов.

Изменение шаблона меняет все блоки, которые его подключают, без ручного копирования.

Интеграция с инструментами

Docker Compose

Docker Compose читает docker-compose.yml и поднимает набор сервисов, сетей и томов. YAML описывает контейнеры, порты, переменные и зависимости.

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    depends_on:
      - db
  db:
    image: postgres:latest
    environment:
    POSTGRES_PASSWORD: example

Ansible

Ansible описывает задачи в playbook-файлах .yml. YAML задает хосты, параметры и шаги. Каждый шаг — это структура данных, которую Ansible сопоставляет модулю и аргументам.

name: Setup web
hosts: webservers
become: true
tasks:
  - name: Install nginx
    apt:
    name: nginx
    state: present

Расширенные формы записи

YAML поддерживает комбинации блочного и потокового стилей, а также многострочные элементы внутри списков и словарей.

menu:
- dish: pasta
  ingredients: [tomato, cheese]
- dish: salad
  ingredients:
    - lettuce
    - |
    long note
    about cucumber

Ограничения и типовые ошибки

YAML удобен, но чувствителен к оформлению. Основные проблемы:

• неверные отступы или смешение табов и пробелов;

• незаметные изменения типа значения (строка стала boolean или timestamp);

• конфликт ключей при merge;

• использование специальных символов без кавычек;

• неодинаковые правила в разных парсерах и версиях спецификации.

Практические требования к качеству YAML

Чтобы конфигурации были стабильными, применяют простые правила:

• единые отступы (часто 2 пробела) и автоматическое форматирование;

• кавычки для спорных значений (yes, no, on, off, 0123, даты);

• явные типы там, где важна строгая интерпретация;

• проверка схемой или тестами в CI, если формат критичен;

• безопасная загрузка YAML в приложениях, без исполнения произвольных тегов.

Валидация и контроль изменений

YAML сам по себе не навязывает схему. Контроль структуры реализуют средствами проекта:

• проверка через JSON Schema после преобразования в JSON-представление;

• линтеры и форматтеры, которые ловят отступы, дубли ключей и стиль;

• юнит-тесты конфигураций, которые проверяют обязательные поля и диапазоны значений.

YAML остается одним из базовых форматов для декларативного описания систем. Его сильная сторона — сочетание строгой структуры и удобства чтения человеком.