YAML: просто о главном

Для конфигурационных файлов существует масса форматов: списки значений, пары «параметр-значение», INI-файлы, YAML, JSON, XML и множество других. Однако по нескольким причинам из всех YAML часто считается особенно трудным. Редакция Highload просто и понятно разъясняет, что такое YAML, а также, какие у него есть возможности/особенности.

Содержание:
1. Что такое YAML
2. Для чего создан YAML
3. Преимущества YAML и примеры использования
4. Отличия YAML от JSON и XML
5. Характерные особенности YAML
6. Синтаксис YAML
Заключение

1. Что такое YAML

YAML — это язык сериализации данных. Он удобен для человека и хорошо работает с различными языками программирования, такими как Perl и Python.

YAML расшифровывается как «YAML Ain’t markup language» хотя ранее эта аббревиатура означала противоположное «Yet Another Markup Language». Название было изменено, чтобы показать, что это не язык разметкикаковым по ошибке его многие восприняли, а язык сериализации данных. Благодаря своим возможностям сериализации этот язык является достойной заменой таким языкам, как JSON и XML. К слову, YAML v1.2 является строгим надмножеством JSON.

2. Для чего создан YAML

YAML создан для упрощения сериализации сложных структур данных. По текущей редакции спецификации YAML v1.2.2 (от 1 октября 2021 года) официальные цели языка таковы:

1. YAML должен легко читаться человеком.
2. YAML должен быть переносимым между языками программирования.
3. YAML должен отвечать встроенным структурам данных динамических языков.
4. YAML должен применять последовательную модель для поддержки общих инструментов.
5. YAML должен поддерживать обработку в один проход.
6. YAML должен быть выразительным и расширяемым.
7. YAML должен быть легким в реализации и использовании.

3. Преимущества YAML и примеры использования

• Удобство восприятия и освоения человеком. Определения структур данных на YAML очень просты для понимания, пользователям легко воспринимать даже сложные структуры данных, описанных на этом языке. Поэтому он прост в изучении.
• Независимость от языка программирования. YAML поддерживает списки (массивы) и словари (ассоциативные массивы, хэши) в форме, понятной для разных языков. Создав определение на YAML один раз, тот же файл можно использовать из файла Python, Ruby и т.д.
• Однозначность. YAML однозначно представляет структуры сериализованных данных, поэтому нет особой необходимости в комментариях и документации. Поскольку структуры данных однозначны, для чтения и записи YAML можно с легкостью использовать сценарии автоматизации. Можно создать сценарий для чтения структуры данных из YAML-файла и ее преобразования в другой формат (JSON или XML).
• Пригодность для контроля версий. Содержимое YAML-файла представляет собой простой текст, и такие файлы можно легко добавлять в репозитории, например, в Git или Subversion.
• Строгость синтаксиса. Спецификация YAML подразумевает минимальную гибкость, что повышает надежность языка.
• Скорость обработки. YAML быстро загружается и легко обрабатывается в памяти.
• Безопасность реализации. Многие проблемы безопасности в языках программирования связаны с анализом недоверенных данных (например, JSON). Java, JavaScript, PHP, Python, Ruby и другие языки дают возможность воспользоваться этими уязвимостями, передавая парсеру строки с непредвиденным содержимым. YAML предназначен для предотвращения этих рисков. Он указывает типы данных для каждого фрагмента потока YAML.

Вот некоторые общие примеры использования YAML:

1. файлы конфигурации (например, для Dancer, Dar, docker-compose, Google App Engine, Ruby on Rails и Symfony);
2. совместное использование данных программами на различных языках;
3. файлы журналов;
4. отладка сложных структур данных;
5. обмен сообщениями между процессами;
6. хранение объектов.

4. Отличия YAML от JSON и XML

Для наглядности приведем примеры описания одной и той же структуры данных на XML, JSON и YAML.

XML

<gas_giants>
    <gas_giant>
        <name>Jupiter</name>
        <mass>1.8982E+27</mass>
        <mean_radius>69.911</mean_radius>
    </gas_giant>
    <gas_giant>
        <name>Saturn</name>
        <mass>5.6834E+26</mass>
        <mean_radius>>58.232</mean_radius>
    </gas_giant>
</gas_giants>

1. XML является языком разметки.
2. В нем используются теги, что снижает удобочитаемость по сравнению с остальными двумя форматами.
3. Схемы позволяют проводить проверки и создавать пользовательские типы.
4. Поддержка пространств имен дают возможность избежать конфликтов имен.
5. Этот формат очень подходит для работы с крупными файлами данных со сложной схемой.

JSON

{
    "gas_giants":
    [
        {
            "name": "Jupiter",
            "mass": 1.8982E+27,
            "mean_radius": 69.911
        },
 
        {
            "name": "Saturn",
            "mass": 5.6834E+26,
            "mean_radius": 58.232
        }
    ]
}

1. JSON — это формат для хранения и передачи данных.
2. Для определения списков и объектов используются квадратные и фигурные скобки.
3. Комментарии не поддерживаются.
4. Более удобочитаем, чем XML, за счет простоты синтаксиса.
5. Превосходит остальные два языка по скорости парсинга и сериализации.
6. Этот формат чаще всего используется в веб-разработке, например, для передачи данных от сервера веб-странице.

YAML

---
gas_giants:
  - name: Jupiter
    mass: 1.8982E+27
    mean_radius: 69.911
  - name: Saturn
    mass: 5.6834E+26
    mean_radius: 58.232

1. YAML позволяет описывать объекты реального мира в удобочитаемом формате.
2. Предоставляет больше возможностей, чем JSON, для создания сложных структур данных. Это строгое надмножество JSON, и поэтому все допустимые документы JSON являются также допустимыми документами YAML.
3. YAML лаконичнее JSON и XML.
4. YAML единственный из этой тройки поддерживает поточную обработку.
5. YAML имеет наименьший размер в сериализованном виде.

5. Характерные особенности YAML

Удобство для чтения

В коде YAML, как и в Python, используются отступы. Но в YAML эти отступы должны быть пробелами, а табуляция не допускается. Для отступа рекомендуется использовать два пробела. Благодаря этому код читается проще, чем JSON и XML: не мешают скобки и кавычки.

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

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

Строки необязательно заключать в кавычки

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

Возможность явного указания типов

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

Ссылки

Ссылки позволяют избежать повторения фрагментов конфигурации.

6. Синтаксис YAML

YAML поддерживает кодировки UTF-8 и UTF-16. Поэтому ключи и значения могут содержать не только латиницу.

В YAML учитывается регистр символов.

Для форматирования структур в YAML используются отступы. Они состоят из пробелов, а табуляция не используется.

Комментарии начинаются с символа «#», от которого он отделяется пробелом.

Списки или массивы

Блочный формат

--- # Список: блочный формат
- Юпитер
- Сатурн
- Уран
- Нептун

В блочном формате элементы списка начинаются с дефиса и пробела.

Встроенный формат

Во встроенном формате элементы списка разделяются запятыми, за которыми следуют обязательные пробелы. Список заключается в квадратные скобки, как в JSON.

--- # Список: в одну строку
  [Юпитер, Сатурн, Уран, Нептун]

Словари или ассоциативные массивы

Словари представлены в виде пар ключей и значений. Значение отделяется от ключа двоеточием и пробелом. Пробел здесь обязателен. В формате JSON словари заключаются в фигурные скобки.

---
# Словарь: блочный формат
Газовые гиганты:
  ледяные:
  - Уран
  -  Нептун
  не ледяные:
  - Юпитер
  - Сатурн
 
  # Словарь: в одну строку
Газовые гиганты: {ледяные: [Уран, Нептун], не ледяные: [Юпитер, Сатурн]}

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

Документы в одном файле разделяются тремя дефисами.

---
планета:
  название: Земля
  спутники: [Луна]
---
планета:
  название: Марс
  спутники: [Фобос, Деймос]

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

Строки

Строки в YAML не обязательно заключать в кавычки. Строки без кавычек могут содержать кавычки.

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

Строки в двойных кавычках могут содержать экранированные символы в стиле языка C.

Это показано в приведенном ниже примере.

no_quotes: This string is not in quotes but it can contain ' and ".
single_quotes: 'This is a string in single quotes. It contains both single ('') and double (") quotes.'
double_quotes: "This is a string in double quotes.\nIt contains both single (') and double (\") quotes\nand a new line characters."

Их внутреннее представление будет таким:

Строки могут записываться и в блочном формате. Если литерал обозначается вертикальной чертой, то пробелы в нем сохраняются. В спецификации YAML 1.2.2 приводится такой пример:

--- |
  \//||\/||
  // ||  ||__

Ведущие пробелы удаляются, а внутренние — сохраняются:

Если литерал обозначается символом «>», то строки складываются в одну, ведущие пробелы удаляются, а внутренние также сохраняются:

--- >
  This line spans
  multiple      lines
  but will be folded.

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

--- >
  This line spans
  multiple lines
    but will be folded
   
  partly.

Теги

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

---
not-date: !!str 2022-01-12

В этом примере значение будет не датой, а строкой.

Многие реализации YAML поддерживают пользовательские типы для сериализации. Это локальные типы. Они обозначаются одним восклицательным знаком и определяются в приложении с помощью библиотеки для парсинга YAML.

---
myCat: !Cat { name: Tom, color: red }

Ссылки

Ссылка обозначается амперсандом (&), а ее значение подставляется с использованием звездочки (*).

---
references:
  val1: &ref This will be repeated
  val2: *ref

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

Другие возможности

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

Заключение

YAML — это понятный, компактный и удобный язык. Его можно использовать в файлах конфигурации для обмена информацией между процессами, хранения объектов и в других целях. Благодаря тому, что YAML является надмножеством JSON, опытному программисту его легко понять и освоить (по аналогии с JSON).

В заключение приводим несколько полезных ссылок для более тесного знакомства с YAML.

• Спецификация редакции v1.2.2.
• Конвертер JSON в YAML.
• Шпаргалка Learn yaml in X minutes.
• Проверка кода YAML.