Что такое YAML? Основы, синтаксис и области применения

За эти годы довелось поработать с бесчисленным количеством файлов конфигураций, и YAML выделяется своей простотой и читаемостью. Будь то настройка рабочих процессов в Kubernetes, описание сервисов в Docker или структурирование API-запросов, YAML делает сложные конфигурации более управляемыми. Его чистая, основанная на отступах структура избавляет от «шума» форматов вроде XML, при этом оставаясь гибкой.

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

Что такое YAML?

YAML (Yet Another Markup Language / YAML Ain’t Markup Language) — это формат сериализации данных, в котором приоритет отдан читаемости и простоте. В то время как XML использует смесь вложенных тегов, похожих на HTML, а JSON — фигурные скобки и кавычки (как в словарях Python), YAML более лаконичен и применяет отступы для определения структуры, что делает его удобным для человека.

YAML поддерживает различные типы данных, включая скаляры (строки, числа, булевы значения), последовательности (списки) и отображения (пары ключ–значение). Его широко используют в конфигурационных файлах, автоматизации инфраструктуры и обмене данными, особенно в таких инструментах, как Kubernetes, Docker и Ansible.

Кроме того, YAML является супермножеством JSON, то есть валидные JSON-файлы можно разобрать как YAML. Файлы YAML обычно имеют расширение .yaml или .yml.

Больше о YAML можно узнать на его официальном сайте.

Синтаксис и структура YAML

В этом разделе разберём базовые принципы синтаксиса YAML, включая пары ключ–значение, списки, вложенные данные и комментарии.

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

Есть несколько основных правил синтаксиса YAML: 

• Структура задаётся пробельными отступами, поэтому избегайте табуляций! 
• Пары ключ–значение имеют вид key: value, как и в других языках. 
• Дефисы в начале строк обозначают список. 
• Символ # создаёт строки комментариев.

# Here is an example of YAML
name: John Doe
age: 30
skills:
  - Python
  - YAML

Пары ключ–значение

YAML представляет данные в виде пар ключ–значение, как словари в Python. Так часто описывают параметры для разных конфигурационных файлов и настроек. Нет необходимости заключать строки или ключи в кавычки — просто укажите нужные ключи и значения:

location: New York
country: USA
security-level: user

Списки в YAML

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

fruits:
  - Apple
  - Banana
  - Cherry

Вложенные данные

Вложенные структуры позволяют иерархически представлять данные с помощью отступов. Представьте их как вложенные словари. Используя отступы, вы указываете, какие ключи являются подмножествами других.

person:
  name: Alice
  details:
    age: 25
    city: London

Комментарии

Комментарии начинаются с # и игнорируются парсерами YAML. Это однострочные комментарии.

# This is a comment
username: admin
password: secret

Продвинутые возможности YAML

YAML включает мощные функции, такие как многострочные строки, типы данных и якори, которые делают документы эффективнее и структурированнее. В этом разделе рассмотрим эти возможности на практических примерах.

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

YAML поддерживает многострочные строки с помощью | (буквальный блок) или > (свёрнутый блок). 

• Буквальный блок | создаёт символ новой строки \n для каждого разрыва строки. 
• Свёрнутый блок > создаёт новую строку только для последовательных разрывов.

literal: |
  This is a
  multi-line string.

folded: >
  This is another
  multi-line string.

Вышеуказанное проще понять на результате.

• Для | (буквального блока):

This is a
multi-line string.

• Для > (свёрнутого блока):

This is another multi-line string.

Типы данных в YAML

YAML поддерживает различные типы данных, включая строки, числа, булевы значения и null. Он автоматически определяет типы по форматированию, но также допускает явные объявления типов.

Ниже показан пример использования базовых типов данных в YAML:

string_implicit: Hello, YAML!  # No quotes needed unless necessary
string_double_quoted: "Supports escape sequences like \n and \t"
string_single_quoted: 'Raw text, no escape sequences'

integer: 42  # Whole numbers
float: 3.14  # Numbers with decimals

boolean_true: true
boolean_false: false

null_value: null  # Null value
null_tilde: ~  # Another way to represent null

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

explicit_string: !!str 123  # Forces 123 to be a string
explicit_integer: !!int "42"  # Forces "42" to be an integer
explicit_float: !!float "3.14"  # Forces "3.14" to be a float

Поскольку YAML часто используют для структурированных данных, он поддерживает:

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

fruits:
  - Apple
  - Banana
  - Cherry

• Словари (отображения):

person:
  name: Alice
  age: 30
  is_student: false

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

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

defaults: &default_settings
  retries: 3
  timeout: 30

server1:
  host: example.com
  retries: *default_settings  # Reuses the retries value from defaults

Синтаксис <<: позволяет сливать пары ключ–значение из якоря в другое отображение. Если ключ присутствует в обоих, новое значение переопределяет исходное.

defaults: &default_settings
  retries: 3
  timeout: 30

server1:
  <<: *default_settings  # Merges all key-value pairs from default_settings
  host: example.com  # This key is added to the merged data

Итоговая развёрнутая структура:

server1:
  retries: 3
  timeout: 30
  host: example.com

Якоря и псевдонимы особенно полезны в крупных конфигурационных файлах, где ручное повторение значений было бы неэффективным. Они помогают держать YAML в стиле DRY (Don't Repeat Yourself) и упрощают обновления.

Распространённые сценарии использования YAML

YAML широко применяют в разработке ПО, автоматизации инфраструктуры и управлении API. Читаемый синтаксис делает его предпочтительным форматом для конфигураций, сериализации данных и описания инфраструктуры как кода (IaC). Рассмотрим самые частые применения.

Конфигурационные файлы

YAML широко используется для конфигураций в приложениях вроде Docker Compose, Kubernetes и конвейеров CI/CD. Благодаря простоте чтения любой человек сможет открыть YAML-файлы Docker и понять, что происходит.

version: '3'
services:
  web:
    image: nginx
    ports:
      - "80:80"
    environment:
      - NGINX_HOST=localhost
      - NGINX_PORT=80

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

Узнайте больше о YAML и его использовании в Docker в этом курсе уровня выше среднего Docker.

Сериализация и передача данных

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

Например, тело запроса к API в формате YAML:

user:
  id: 123
  name: "John Doe"
  email: "johndoe@example.com"
  active: true

Структура YAML, основанная на отступах, устраняет лишний синтаксис, делая его легче, читабельнее и проще в редактировании по сравнению с JSON.

Инфраструктура как код (IaC)

Инструменты управления конфигурациями, такие как Ansible и Kubernetes, используют YAML для описания состояний систем, автоматизации процессов и обеспечения согласованности между средами.

• В Ansible YAML применяют для написания плейбуков, определяющих состояния системы, задачи и зависимости, чтобы компоненты инфраструктуры настраивались единообразно. 
• Kubernetes использует YAML-манифесты для описания ресурсов, таких как поды, сервисы и деплойменты, что позволяет автоматически оркестрировать контейнеризованные приложения.

Вот пример конфигурации пода в Kubernetes:

apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  containers:
    - name: app-container
      image: my-app:latest
      ports:
        - containerPort: 8080

Узнайте больше о том, как YAML используется в Кубernetes, в курсе Introduction to Kubernetes.

Документация API

Спецификации API, такие как OpenAPI и Swagger, используют YAML для удобного описания эндпоинтов и структур данных. На YAML определяют методы API, параметры запросов, форматы ответов и методы аутентификации.

Пример спецификации OpenAPI на YAML:

openapi: 3.0.0
info:
  title: User API
  version: "1.0"
paths:
  /users:
    get:
      summary: Retrieve a list of users
      responses:
        "200":
          description: Successful response

Например, спецификации OpenAPI используют YAML для документирования RESTful API. Это позволяет создавать понятный чертёж для генерации клиентских SDK, интерактивной документации и автоматизированного тестирования. Такая структура обеспечивает единообразие реализаций API.

Работа с файлами YAML

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

Чтение и запись YAML в Python

Библиотека Python PyYAML умеет разбирать и генерировать YAML.

Представьте, что у вас есть следующий конфигурационный файл YAML:

database:
  host: localhost
  port: 5432
  user: admin
  password: secret

Вот как можно работать с этим конфигурационным файлом в Python:

import yaml

# Load YAML data
with open("config.yaml", "r") as file:
    data = yaml.safe_load(file)  # safe_load prevents arbitrary code execution

# Modify data (optional)
data["database"]["user"] = "new_user"

# Write YAML data
with open("output.yaml", "w") as file:
    yaml.dump(data, file, default_flow_style=False)

Если вас интересует работа с данными JSON в Python, загляните в подробное руководство по JSON в Python.

Проверка (валидация) файлов YAML

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

Вот несколько популярных валидаторов YAML:

• CLI-инструмент: yamllint (линтер на Python)
• Онлайн-валидаторы: YAML Lint, YAML Validator от JSON Formatter

Редактирование YAML

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

Некоторые из любимых редакторов:

• VS Code (с плагинами для YAML)
• PyCharm (встроенная поддержка)
• Sublime Text (с подсветкой YAML)

Типичные ошибки в YAML и как их избежать

Несмотря на простоту, при работе с YAML легко допустить ошибки и опечатки. В этом разделе мы обсудим такие ошибки и дадим рекомендации по написанию чистых и корректных файлов. Именно поэтому стоит пользоваться линтером или продвинутым редактором!

Смешение табов и пробелов

YAML опирается на пробелы для отступов — никогда не смешивайте пробелы и табуляции. Табуляции просто сломают ваш YAML. Это осознанное решение: разные системы по-разному интерпретируют табы, поэтому во избежание проблем предпочтительны пробелы.

Неверные отступы

Обеспечьте единообразные отступы, чтобы избежать ошибок парсинга. Поскольку отступы — единственный способ обозначить иерархию в YAML, неправильный парсинг может вызвать проблемы в коде. Легко «спрятать» пару key: value не в том месте, поэтому следите за отступами!

Забытые кавычки для специальных символов

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

path: "/home/user/documents"
message: "Hello, World!"

Используя корректную валидацию, структурированное редактирование и Python-библиотеку PyYAML, вы сможете эффективно работать с файлами YAML и избегать распространённых ошибок.

Заключение

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

Если вы хотите применить YAML на практике:

• Узнайте, как YAML используется в рабочем процессе CI/CD, в курсе CI/CD для машинного обучения.
• Посмотрите, как API используют YAML в своих спецификациях, в курсе Введение в API на Python.
• Погрузитесь глубже в контейнеризацию и автоматизацию инфраструктуры в треке Контейнеризация и виртуализация.