YAML: Человекочитаемый формат сериализации данных

Введение

CSS фреймворк. Человекочитаемый формат сериализации данных.

YAML (/'//j//æ//m//ə//l/; см.) — это человекочитаемый язык сериализации данных. Он широко используется для файлов конфигурации и в приложениях, где данные хранятся или передаются. YAML ориентирован на многие из тех же коммуникационных задач, что и Extensible Markup Language (XML), но имеет минималистичный синтаксис, намеренно отличающийся от Standard Generalized Markup Language (SGML), и не требует кавычек вокруг большинства строковых значений (поддерживает также стиль JSON и их смешанное использование в одном файле). Допускаются пользовательские типы данных, но YAML изначально кодирует скаляры (такие как строки, целые числа и числа с плавающей точкой), списки и ассоциативные массивы (также известные как карты, словари или хеши). Эти типы данных основаны на языке программирования Perl, хотя все широко используемые языки программирования высокого уровня имеют очень похожие концепции. Синтаксис с двоеточием для обозначения пар ключ-значение вдохновлен заголовками электронной почты, определенными в , а разделитель документов заимствован из MIME. Экранирующие последовательности используются из C, а переносы строк для многострочных строк вдохновлены HTML. Списки и хеши могут содержать вложенные списки и хеши, образуя древовидную структуру; произвольные графы могут быть представлены с использованием YAML-алиасов (аналогично XML в SOAP). Некоторые редакторы исходного кода, такие как Vim, Emacs и различные интегрированные среды разработки, имеют функции, облегчающие редактирование YAML, например, сворачивание вложенных структур или автоматическое выделение синтаксических ошибок. Официально рекомендованное расширение имени файла для файлов YAML — с 2006 года. В 2024 году был окончательно утвержден MIME-тип . Разработан вместе с Инги дёт Нет и Ореном Бен Кики, поскольку был выпущен в эпоху расцвета языков разметки для представления и обмена данными (HTML, XML, SGML и т. д.). Первоначальное название было задумано как ироничная отсылка к технологическому ландшафту, подчеркивающая его назначение как еще одного языка разметки, но затем было переосмыслено как YAML Ain't Markup Language — рекурсивный акроним, чтобы подчеркнуть его ориентацию на данные, а не на разметку документов.

YAML (/'//j//æ//m//ə//l/; see ) is a human readable data serialization language. It is commonly used for configuration files and in applications where data are being stored or transmitted. YAML targets many of the same communications applications as Extensible Markup Language (XML) but has a minimal syntax that intentionally differs from Standard Generalized Markup Language (SGML). and does not require quotes around most string values (it also supports JSON style and mixed in the same file). Custom data types are allowed, but YAML natively encodes scalars (such as strings, integers, and floats), lists, and associative arrays (also known as maps, dictionaries or hashes). These data types are based on the Perl programming language, though all commonly used high level programming languages share very similar concepts. The colon centered syntax, used for expressing key value pairs, is inspired by electronic mail headers as defined in , and the document separator is borrowed from MIME Escape sequences are reused from C, and whitespace wrapping for multi line strings is inspired by HTML. Lists and hashes can contain nested lists and hashes, forming a tree structure; arbitrary graphs can be represented using YAML aliases (similar to XML in SOAP). Some source code editors such as Vim, Emacs, and various integrated development environments have features that make editing YAML easier, such as folding up nested structures or automatically highlighting syntax errors. The official recommended filename extension for YAML files has been since 2006. In 2024, the MIME type has been finalized. who designed it together with Ingy döt Net and Oren Ben Kiki. because it was released in an era that saw a proliferation of markup languages for presentation and connectivity (HTML, XML, SGML, etc). Its initial name was intended as a tongue in cheek reference to the technology landscape, referencing its purpose as a markup language with the yet another construct, but it was then repurposed as YAML Ain't Markup Language, a recursive acronym, to distinguish its purpose as data oriented, rather than document markup.

Версии

Версия Дата выхода YAML 1.0 YAML 1.1 YAML 1.2.0 YAML 1.2.1 YAML 1.2.2

Синтаксис

Лист и полная спецификация доступны на официальном сайте. Ниже приводится краткое изложение основных элементов. YAML принимает весь набор символов Unicode, за исключением некоторых управляющих символов, и может быть закодирован в UTF-8, UTF-16 или UTF-32. (Хотя UTF-32 не является обязательным, он требуется для обеспечения совместимости с JSON для парсера.) Отступы пробелами используются для обозначения структуры; однако символы табуляции не допускаются в качестве части этих отступов. Комментарии начинаются со знака решётки (#), могут начинаться в любом месте строки и продолжаться до её конца. Комментарии должны быть отделены от других токенов пробельными символами. Если символы # встречаются внутри строки, они рассматриваются как литеральные знаки решётки. Элементы списка обозначаются дефисом (-) в начале строки, по одному элементу на строку. Список также можно задать, заключив текст в квадратные скобки [], при этом каждый элемент разделяется запятой. Элемент ассоциативного массива представляется в виде "ключ: значение" с одним элементом на строку. YAML требует, чтобы после двоеточия следовал пробел, чтобы строки в стиле URL могли быть представлены без кавычек. Знак вопроса (?) может быть использован перед ключом в форме "?ключ: значение", чтобы ключ мог содержать начальные дефисы, квадратные скобки и т. д. без кавычек. Ассоциативный массив также можно задать текстом, заключённым в фигурные скобки {}, с ключами, отделёнными от значений двоеточием, а элементы – запятыми (пробелы не требуются для сохранения совместимости с JSON). Строки (один из типов скалярных значений в YAML) обычно не заключаются в кавычки, но могут быть заключены в двойные кавычки " или одинарные кавычки '. Внутри двойных кавычек специальные символы могут быть представлены последовательностями экранирования в стиле C, начинающимися с обратной косой черты \. Согласно документации, поддерживается только восьмеричное экранирование. Внутри одинарных кавычек поддерживается только одна последовательность экранирования – удвоенная одинарная кавычка ', обозначающая саму одинарную кавычку, например ''. Блочные скалярные значения ограничиваются отступами с необязательными модификаторами для сохранения (|) или переноса (|) новых строк. Несколько документов в одном потоке разделяются тремя дефисами ---. Три точки ... необязательно завершают документ в потоке. Повторяющиеся узлы первоначально обозначаются амперсандом &, а затем ссылаются на них с помощью звездочки *. Узлы могут быть помечены типом или тегом с помощью двойного восклицательного знака !!, за которым следует строка, которая может быть расширена до URI. Документам YAML в потоке могут предшествовать "директивы", состоящие из знака процента %, за которым следует имя и параметры, разделенные пробелом. В YAML 1.1 определены две директивы: директива %YAML используется для идентификации версии YAML в данном документе. Директива %TAG используется в качестве сокращения для префиксов URI. Эти сокращения затем могут быть использованы в тегах типов узлов.

A cheat sheet and full specification are available at the official site. The following is a synopsis of the basic elements. YAML accepts the entire Unicode character set, except for some control characters, and may be encoded in any one of UTF 8, UTF 16 or UTF 32. (Though UTF 32 is not mandatory, it is required for a parser to have JSON compatibility.) Whitespace indentation is used for denoting structure; however, tab characters are not allowed as part of that indentation. Comments begin with the number sign , can start anywhere on a line and continue until the end of the line. Comments must be separated from other tokens by whitespace characters. If # characters appear inside of a string, then they are number sign literals. List members are denoted by a leading hyphen with one member per line. A list can also be specified by enclosing text in square brackets with each entry separated by a comma. An associative array entry is represented using colon space in the form key: value with one entry per line. YAML requires the colon be followed by a space so that url style strings like can be represented without needing to be enclosed in quotes. A question mark can be used in front of a key, in the form "?key: value" to allow the key to contain leading dashes, square brackets, etc., without quotes. An associative array can also be specified by text enclosed in curly braces , with keys separated from values by colon and the entries separated by commas (spaces are not required to retain compatibility with JSON). Strings (one type of scalar in YAML) are ordinarily unquoted, but may be enclosed in double quotes , or single quotes Within double quotes, special characters may be represented with C style escape sequences starting with a backslash According to the documentation the only octal escape supported is Within single quotes the only supported escape sequence is a doubled single quote denoting the single quote itself as in Block scalars are delimited with indentation with optional modifiers to preserve (|) or fold newlines. Multiple documents within a single stream are separated by three hyphens Three periods optionally end a document within a stream. Repeated nodes are initially denoted by an ampersand and thereafter referenced with an asterisk Nodes may be labeled with a type or tag using a double exclamation mark followed by a string, which can be expanded into a URI. YAML documents in a stream may be preceded by 'directives' composed of a percent sign followed by a name and space delimited parameters. Two directives are defined in YAML 1.1:
The %YAML directive is used for identifying the version of YAML in a given document. The %TAG directive is used as a shortcut for URI prefixes. These shortcuts may then be used in node type tags.

Современные компоненты

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

Практические соображения

YAML ориентирован на строки, и поэтому часто бывает просто преобразовать неструктурированный вывод существующих программ в формат YAML, сохраняя при этом большую часть внешнего вида исходного документа. Поскольку в YAML отсутствуют закрывающие теги, скобки или кавычки, требующие балансировки, обычно легко генерировать корректный YAML непосредственно из распределенных операторов печати в простых программах. Аналогичным образом, разделители на основе пробелов облегчают быструю и простую фильтрацию файлов YAML с помощью строкоориентированных команд в grep, AWK, Perl, Ruby и Python. В частности, в отличие от языков разметки, последовательные строки YAML часто сами по себе являются корректными документами YAML. Это позволяет легко создавать парсеры, которым не требуется обрабатывать документ целиком (например, балансировать открывающие и закрывающие теги и обрабатывать заключенные в кавычки и экранированные символы), прежде чем они начнут извлекать конкретные записи. Это свойство особенно полезно при итерации в одном, без сохранения состояния, проходе по записям в файле, чья полная структура данных слишком велика для хранения в памяти, или для которого восстановление всей структуры для извлечения одного элемента было бы непомерно дорогостоящим. Вопреки интуиции, хотя отступы могут казаться усложняющими глубоко вложенные иерархии, YAML обрабатывает отступы, равные даже одному пробелу, что может обеспечить лучшее сжатие, чем языки разметки. Кроме того, чрезмерно глубоких отступов можно полностью избежать либо: 1) переходом к "встроенному стилю" (то есть формату, похожему на JSON) без отступов; либо 2) использованием реляционных якорей для развертывания иерархии в плоскую форму, которую парсер YAML будет прозрачно восстанавливать в полную структуру данных.

Безопасность

YAML - это чисто язык представления данных и, следовательно, не содержит исполняемых команд. Хотя валидация и безопасный разбор данных принципиально возможны в любом языке данных, реализация часто сопряжена с серьезными ошибками, поэтому отсутствие связанного языка команд в YAML может являться относительным преимуществом с точки зрения безопасности. Однако YAML допускает использование тегов, специфичных для языка, что позволяет парсеру, поддерживающему эти теги, создавать произвольные локальные объекты. Любой YAML-парсер, допускающий сложное создание экземпляров объектов, открывает потенциальную возможность для инъекционной атаки. Perl-парсеры, позволяющие загружать объекты произвольных классов, создают так называемые "благословленные" значения. Использование этих значений может привести к неожиданному поведению, например, если класс использует перегруженные операторы. Это может привести к выполнению произвольного кода Perl. Аналогичная ситуация наблюдается и для парсеров Python или Ruby. Согласно документации PyYAML:

Обратите внимание, что возможность создания произвольного объекта Python может быть опасной, если вы получаете YAML-документ из ненадежного источника, например, из Интернета. Функция ограничивает эту возможность простыми объектами Python, такими как целые числа или списки. [ ]

PyYAML позволяет создавать объекты Python любого типа. Даже экземпляры классов Python могут быть созданы с использованием тега.

Обработка и представление данных

Спецификация YAML определяет экземпляр документа как "презентацию" или "поток символов". Основными логическими структурами в документе YAML являются скаляры, последовательности и отображения. Спецификация YAML также устанавливает некоторые базовые ограничения, применимые к этим основным логическим структурам. Например, согласно спецификации, порядок ключей в отображениях не имеет значения. В любом случае, когда порядок узлов существенен, необходимо использовать последовательность. Более того, при определении соответствия процессоров YAML спецификация определяет две основные операции: дамп и загрузка. Все процессоры, соответствующие требованиям YAML, должны поддерживать как минимум одну из этих операций, и могут поддерживать обе. Наконец, спецификация YAML определяет информационную модель или "граф представления", который должен создаваться в процессе обработки как для операции дампа, так и для операции загрузки, хотя это представление необязательно должно быть доступно пользователю через API.

Сравнение с JSON

Синтаксис JSON является основой версии YAML 1.2, которая была опубликована с четкой целью привести YAML "в соответствие с JSON как с официальным подмножеством". Различия были редко заметны, и большинство JSON-документов могут быть разобраны некоторыми YAML-парсерами, такими как Syck. Это происходит потому, что семантическая структура JSON эквивалентна необязательному "встроенному стилю" записи YAML. Хотя разветвленные иерархии могут быть записаны во встроенном стиле, как в JSON, это не является рекомендуемым стилем YAML, за исключением случаев, когда это способствует ясности. YAML обладает множеством дополнительных функций, которых нет в JSON, включая комментарии, расширяемые типы данных, реляционные якоря, строки без кавычек и типы отображений, сохраняющие порядок ключей. Благодаря своей лаконичности, сериализация и десериализация JSON значительно быстрее, чем YAML.

Сравнение с TOML

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

Сравнение с XML

В YAML отсутствует понятие атрибутов тегов, как в XML. Вместо этого YAML использует расширяемые объявления типов (включая типы классов для объектов). Сам по себе YAML не имеет встроенных описателей схем документов, определенных языком, как в XML, которые позволяли бы документу самопроверяться. Однако существует несколько внешних языков описания схем для YAML (например, Doctrine, Kwalify и Rx), выполняющих эту функцию. Более того, семантика, обеспечиваемая объявлениями типов, определенными в самом документе YAML, часто снижает потребность в валидаторе в простых и распространенных случаях. Кроме того, YAXML, представляющий структуры данных YAML в формате XML, позволяет применять к YAML импортеры схем XML и механизмы вывода, такие как XSLT. Более полное сравнение YAML с другими форматами сериализации представлено в разделе "Сравнение форматов сериализации данных".

Программное обеспечение (эмиттеры и анализаторы)

Для фиксированных структур данных файлы YAML могут быть просто сгенерированы с помощью команд печати, которые записывают как данные, так и специфическое оформление YAML. Однако для вывода изменяющихся или сложных иерархических данных предпочтительнее использовать выделенный YAML-излучатель. Аналогично, простые файлы YAML (например, пары ключ-значение) легко разбираются с помощью регулярных выражений. Для более сложных или изменяющихся структур данных рекомендуется использовать формальный YAML-парсер. YAML-излучатели и парсеры существуют для многих популярных языков программирования. Большинство из них написаны на родном языке. Некоторые являются языковыми привязками к C-библиотеке libyaml; они могут работать быстрее. Ранее существовала другая C-библиотека под названием Syck, написанная и заброшенная why the lucky stiff: она больше не поддерживается, нет авторитетного исходного пакета, а веб-сайт был взломан. Следовательно, единственной рекомендуемой C-библиотекой является libyaml. Она была первоначально разработана Кириллом Симоновым. В 2018 году разработка была возобновлена новыми сопровождающими Ианом Кордаско и Инги дёт Нет. Программисты на C++ могут выбирать между C-библиотекой libyaml и C++-библиотекой libyaml-cpp. Обе имеют полностью независимые кодовые базы и совершенно разные API. Библиотека libyaml-cpp по-прежнему имеет мажорный номер версии 0, что указывает на то, что API может измениться в любой момент, как это и произошло после версии 0.3. Существует реализация, ориентированная на грамматику, написанная на C#, с целью расширения для вложенных элементов. Некоторые реализации YAML, такие как Perl's YAML.pm, загружают весь файл (поток) и разбирают его целиком. Другие реализации, такие как PyYaml, ленивы и переходят к следующему документу только по запросу. Для очень больших файлов, в которых планируется обрабатывать документы независимо, создание экземпляра всего файла перед обработкой может быть нецелесообразным. Таким образом, в YAML.pm иногда необходимо разбивать файл на документы и разбирать их по отдельности. YAML упрощает это, поскольку для этого достаточно разделить файл по конечному маркеру документа, который определяется как три точки в начале строки, за которыми следует пробел (и, возможно, комментарий). Этот маркер запрещен в содержимом.

For fixed data structures, YAML files can simply be generated using print commands that write both the data and the YAML specific decoration. To dump varying, or complex, hierarchical data, however, a dedicated YAML emitter is preferable. Similarly, simple YAML files (e. g. key value pairs) are readily parsed with regular expressions. For more complex, or varying, data structures, a formal YAML parser is recommended. YAML emitters and parsers exist for many popular languages. Most of them are written in the native language itself. Some are language bindings of the C library libyaml; they may run faster. There used to be another C library, called Syck, written and orphaned by why the lucky stiff: it is unmaintained, there is no authoritative source bundle, and the web site has been hijacked. Hence the only recommendable C library is libyaml. It was originally developed by Kirill Simonov. In 2018, development was resumed by the new maintainers Ian Cordasco and Ingy döt Net. C++ programmers have the choice between the C library libyaml and the C++ library libyaml cpp. Both have completely independent code bases and completely different APIs. The library libyaml cpp still has a major version number of 0, indicating that the API may change at any moment, as happened indeed after version 0.3. There is a grammar focused implementation written in C#, with an aim on extensions for the nested elements. Some implementations of YAML, such as Perl's YAML. pm, will load an entire file (stream) and parse it en masse. Other implementations like PyYaml are lazy and iterate over the next document only upon request. For very large files in which one plans to handle the documents independently, instantiating the entire file before processing may be prohibitive. Thus in YAML. pm, occasionally one must chunk a file into documents and parse those individually. YAML makes this easy, since this simply requires splitting on the document end marker, which is defined as three periods at the start of a line followed by a whitespace (and possible a comment). This marker is forbidden in content.