{"id":3449,"date":"2024-01-11T02:15:00","date_gmt":"2024-01-11T07:15:00","guid":{"rendered":"https:\/\/www.both.org\/?p=3449"},"modified":"2024-01-07T21:13:36","modified_gmt":"2024-01-08T02:13:36","slug":"how-yaml-actually-works","status":"publish","type":"post","link":"https:\/\/www.both.org\/?p=3449","title":{"rendered":"How YAML actually works"},"content":{"rendered":"
\r\n
\r\n \r\n <\/i>\r\n <\/a>\r\n <\/span>\r\n<\/div><\/div>\n

Image by: Opensource.com CC-by-SA 4.0<\/p>\n\n\n\n

YAML stands for “YAML Ain’t Markup Language” and it’s described on YAML.org<\/a> as a human-friendly data serialization language. In other words, it’s a standardized way to make a list. To ensure that the list you make can be reliably parsed, though, there are strict rules around how YAML is formatted, and that sometimes confuses new YAML users.<\/p>\n\n\n\n

The good news is that YAML is essentially governed by just three principles.<\/p>\n\n\n\n

Indent your YAML<\/h2>\n\n\n\n

The first rule of YAML formatting is that each node in your list must be indented further than its parent node, and all sibling nodes use the same indentation.<\/p>\n\n\n\n

For example, suppose you have the item operating system<\/code> in a YAML list. This item contains Linux<\/code> and BSD<\/code>. The child elements (Linux<\/code> and BSD<\/code>) must each be indented to the right more than the operating system<\/code> element, but equal to one another.<\/p>\n\n\n\n

---\n- operating systems:\n  - Linux\n  - BSD<\/code><\/pre>\n\n\n\n
It’s a common convention to indent in multiples of two, probably because one space is harder to notice at a glance compared to two spaces. It’s not technically required to indent in multiples of two, but many YAML linters (applications that verify valid YAML) return warnings for indents with odd numbers of spaces.<\/p>\n\n\n\n
Create a sequence in YAML<\/h2>\n\n\n\n
The second principle of YAML is the sequence<\/em> datatype. This is the simplest datatype in YAML, and it’s basically a fancy term for “list”, which is exactly what it constructs. When you list singular items (called a scalar<\/em> in YAML) on a separate line, you create a sequence.<\/p>\n\n\n\n
Simple though it may seem, this is a valid YAML sequence:<\/p>\n\n\n\n
---\nLinux\nBSD\nIllumos<\/code><\/pre>\n\n\n\n
It’s also valid to write it with dashes in front:<\/p>\n\n\n\n
---\n- Linux\n- BSD\n- Illumos<\/code><\/pre>\n\n\n\n
That’s all a sequence is. There are no child nodes in a sequence, because a sequence is just a list of singular items, one item on each line. For a child node, you need a mapping<\/em>.<\/p>\n\n\n\n
Create a mapping in YAML<\/h2>\n\n\n\n
The third principle of YAML is the mapping<\/em> datatype. A mapping is a key and value pair. When you want to include a term and its definition in a YAML file, then you use a mapping.<\/p>\n\n\n\n
This is a valid mapping in YAML:<\/p>\n\n\n\n
---\nOS: Linux<\/code><\/pre>\n\n\n\n
As you might guess, you can have a sequence of mappings:<\/p>\n\n\n\n
---\nOS: Linux\nCPU: AMD\nRAM: 32G<\/code><\/pre>\n\n\n\n
As usual, you can also write this with dashes as bullet points:<\/p>\n\n\n\n
---\n- OS: Linux\n- CPU: AMD\n- RAM: 32G<\/code><\/pre>\n\n\n\n
That’s not all you can do with a mapping, though. You can also include a sequence within a mapping! You’ve already seen this in this very article, in fact. My first example of YAML was a mapping containing a sequence:<\/p>\n\n\n\n
---\noperating systems:\n  - Linux\n  - BSD<\/code><\/pre>\n\n\n\n
This maps the values Linux<\/code> and BSD<\/code> to the parent node operating system<\/code>.<\/p>\n\n\n\n
Making YAML simple<\/h2>\n\n\n\n
You now know everything you need to know about YAML! You can learn more about further features of the format (such as commenting, line breaks, null nodes, and so on) by reading the official YAML specification<\/a>, but what you’ve learnt in this article may be all you ever need.<\/p>\n\n\n\n
In addition to the basics I’ve provided in this article, there are two general rules to keep in mind:<\/p>\n\n\n\n
    \n
  1. Use yamllint<\/code> or some kind of linter or validator before committing your YAML to production. A good linter alerts you of suboptimal syntax that could cause some parsers (human or computer) trouble and, most importantly, catches errors that definitely render your YAML unusable.<\/li>\n\n\n\n
  2. When in doubt, keep in mind the three principles described in this article! These are the building blocks of YAML: sequence, mapping, and indentation. When a linter throws an error, it means you’ve violated one of these principles. Look at the offending line and determine whether it’s a sequence or a mapping, and verify indentation.<\/li>\n<\/ol>\n\n\n\n
    YAML is designed to be easy, but often when something is simple in technology it’s because it maintains strict rules that can’t withstand variation. Don’t confuse YAML with an arbitrary bullet point list you jot down in a notebook before you go shopping. YAML is a simple database of information, carefully structured for reliable parsing. Learn it once, and write it well.<\/p>\n","protected":false},"excerpt":{"rendered":"
    Learn how to create YAML correctly from the start.<\/p>\n","protected":false},"author":31,"featured_media":3307,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_lmt_disableupdate":"","_lmt_disable":"","footnotes":""},"categories":[5],"tags":[152,97],"class_list":["post-3449","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-linux","tag-programming","tag-sysadmin"],"modified_by":"David Both","_links":{"self":[{"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts\/3449","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/users\/31"}],"replies":[{"embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=3449"}],"version-history":[{"count":3,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts\/3449\/revisions"}],"predecessor-version":[{"id":3463,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/posts\/3449\/revisions\/3463"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=\/wp\/v2\/media\/3307"}],"wp:attachment":[{"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=3449"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=3449"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.both.org\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=3449"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}