Учебник по синтаксису YAML: практическое введение

YAML (YAML Ain't Markup Language) — это человекочитаемый формат сериализации данных, широко используемый в конфигурационных файлах, CI/CD-пайплайнах и инфраструктуре как коде. Если вы работаете с Docker Compose, Kubernetes, GitHub Actions или Ansible, вы уже используете YAML каждый день. Этот учебник охватывает всё необходимое для уверенного написания YAML.

Почему YAML?

Главное преимущество YAML — читаемость. Сравните одни и те же данные в JSON и YAML:

JSON:

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true,
    "allowed_origins": ["http://localhost:3000", "https://example.com"]
  }
}

YAML:

server:
  host: localhost
  port: 8080
  debug: true
  allowed_origins:
    - http://localhost:3000
    - https://example.com

YAML достигает той же структуры с меньшим количеством пунктуации. Нет фигурных скобок, нет квадратных скобок в простых случаях, не требуется обязательное кавычение. Это делает конфигурационные файлы проще для чтения и ручного редактирования.

Базовые типы данных

Скаляры

YAML автоматически определяет типы по значениям:

string: hello world          # String (no quotes needed)
quoted: "hello world"        # Explicit string
integer: 42                  # Integer
float: 3.14                  # Float
boolean: true                # Boolean (true/false, yes/no, on/off)
null_value: null             # Null (also ~ or empty)
date: 2025-01-15             # Date (ISO 8601)

Типичная ошибка: значения yes, no, on, off интерпретируются как булевые. Если вы имеете в виду строку "yes", заключите её в кавычки: "yes".

Строки и кавычки

Строки редко нуждаются в кавычках, но в некоторых случаях они необходимы:

plain: This is a plain string
single: 'Preserves \n as literal backslash-n'
double: "Interprets \n as newline"
colon: "value: with colon needs quotes"
hash: "value # with hash needs quotes"

Многострочные строки

YAML имеет два многострочных стиля:

Литеральный блок (|) — сохраняет переводы строк:

description: |
  This is line one.
  This is line two.
  
  This is line four (after blank line).

Свёрнутый блок (>) — объединяет строки пробелами:

description: >
  This is a long paragraph
  that will be folded into
  a single line.

Добавьте -, чтобы убрать завершающий перевод строки (|-, >-), или +, чтобы сохранить (|+, >+).

Коллекции

Списки (последовательности)

# Block style
fruits:
  - apple
  - banana
  - cherry

# Flow style (inline)
fruits: [apple, banana, cherry]

Отображения (маппинги)

# Block style
person:
  name: Alice
  age: 30
  city: London

# Flow style
person: {name: Alice, age: 30, city: London}

Вложенные структуры

departments:
  - name: Engineering
    lead: Alice
    members:
      - Bob
      - Charlie
  - name: Design
    lead: Diana
    members:
      - Eve

Якоря и псевдонимы

Якоря (&) и псевдонимы (*) позволяют повторно использовать значения:

defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

development:
  database: dev_db
  <<: *defaults

production:
  database: prod_db
  <<: *defaults
  host: db.example.com  # Override the default

Ключ слияния << включает все свойства из якоря. Свойства, определённые после слияния, переопределяют значения якоря. Подробнее о продвинутых паттернах якорей читайте в нашем руководстве по якорям и псевдонимам YAML.

Множественные документы

Один YAML-файл может содержать несколько документов, разделённых ---:

---
# Document 1: Config
apiVersion: v1
kind: ConfigMap
---
# Document 2: Service
apiVersion: v1
kind: Service

Это часто используется в манифестах Kubernetes.

Типичные ошибки

1. Ошибки отступов

YAML использует пробелы, никогда табуляцию. Непоследовательные отступы — самая распространённая ошибка:

# WRONG - mixed indentation
server:
  host: localhost
    port: 8080  # Error: unexpected indentation

# CORRECT
server:
  host: localhost
  port: 8080

Используйте наш YAML Formatter для автоматического исправления отступов.

2. Проблема Норвегии

Коды стран вроде NO (Норвегия) интерпретируются как булево false:

# WRONG
countries:
  - NO  # Interpreted as false!
  - SE
  - DK

# CORRECT
countries:
  - "NO"
  - SE
  - DK

3. Специальные символы без кавычек

Двоеточия, решётки и скобки в значениях требуют кавычек:

# WRONG
message: Error: file not found
url: http://example.com  # Might break

# CORRECT
message: "Error: file not found"
url: "http://example.com"

4. Ловушка с номерами версий

Номера версий вроде 1.0 разбираются как числа с плавающей точкой:

# WRONG
version: 1.0  # Becomes 1 (float)

# CORRECT
version: "1.0"  # String

Валидация YAML

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

Для более глубокого сравнения YAML и JSON смотрите наше сравнение YAML vs JSON.

Часто задаваемые вопросы

Сколько пробелов использовать для отступов в YAML?

Два пробела — наиболее распространённая конвенция, используемая в Kubernetes, Docker Compose, GitHub Actions и большинстве DevOps-инструментов. Некоторые проекты используют четыре пробела. Ключевое правило — единообразие в пределах файла: никогда не смешивайте уровни отступов.

Поддерживает ли YAML комментарии?

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

Связанные ресурсы

• YAML Formatter — форматирование и украшение YAML-файлов
• YAML vs JSON — когда использовать какой формат
• YAML для Docker Compose — паттерны YAML для Docker