YAML Includes Atoms, Maps, and Lists (Featuring the String ¯∖_(ツ)_/¯)
Updated 2021-August-28

Page contents

News

2020-November-10  As of today, this evolving⁠[1] article has been on the web for 1 year.🎂

What is YAML?

YAML is a configuration language and data-serialization format that can include Atoms, Maps and Lists.[2]

Atoms are the elementary particles of a YAML serialization. An atom is usually either…

  • a boolean (e.g. true or false),

  • a number (e.g. 6 or 6.283185307),

  • or a string (e.g. hello world or ¯∖_(ツ)_/¯).

A map is a key-value pair. Here are a couple example YAML maps:

key1: value1
key2: value2

Here is an example of a YAML list:

- item1
- item2
- item3

These data structures can have names, also known as keys. For example:

name1:
  key1: value1
  key2: value2

name2:
  - item1
  - item2
  - item3

Note that name1 is a key whose value is a couple maps and name2 is a key whose value is a three-item list. Naming a collection is a way to turn it into a block or object (with sub-objects) that can be referenced.

 

Terminology

An atom is also known as a scalar.

A list is also known as an array, a sequence, a slice, or a vector.

A named collection of maps, for example name1, is also known as an associative array, a dictionary, a dict, a hash table, a hash, a keyed list, a map, a mapping, a named map, a nested map, an object, a record, a struct, or a table.

 

Example 1: Excerpt of a Hugo config.yaml

Here is an excerpt of the config.yaml that Hugo uses to generate the Infinite Ink website.

markup:
 asciidocExt:
  preserveTOC: true
  workingFolderCurrent: false  # default is false
  attributes:
   toc: macro
   hide-uri-scheme: true@  # trailing @ means ok to override
   sectlinks: true
   huri-config-vars: https://gohugo.io/getting-started/configuration/
   huri-page-vars: https://gohugo.io/variables/page/
   huri-site-vars: https://gohugo.io/variables/site/
   huri-file-vars: https://gohugo.io/variables/files/

 

To learn about the above config.yaml excerpt, see section 2 of Infinite Ink’s Intertwingling AsciiDoc and Hugo⁠.

 

Example 2: This article’s front matter

The following is the YAML front matter that is at the top of the source of this article.

---
draft: false

title: 'YAML Includes Atoms, Maps, and Lists (Featuring the String ¯∖_(ツ)_/¯)'
linkTitle: YAML Includes Atoms, Maps, and Lists

publishDate: 2019-11-10
lastmod: 2021-08-28

tags:
  - content
  - emoji
  - gohugo
  - iusethis
  - n2s
  - tech
---

 

The value of the title key needs to be quoted because it is a string that contains a backslash (\), which is a character that has a special meaning in YAML. To learn about quoting in YAML, see www.yaml.info/learn/quote.html.

 

To learn about the shruggie emoticon (¯\_(ツ)_/¯), see emojipedia.org/person-shrugging/.

 

YAML syntax tips

In general, you do not need to use quotation marks around YAML strings, but quoting a string might be needed if it…

  • includes any of the following 14 characters, which can have a special meaning in YAML: : - { } [ ] ! # | > & % @ \

Quoting a string is needed if it…

  • looks like a number (decimal, hexadecimal, exponential E or e notation, etc.)

  • or is one of YAML’s reserved boolean words (true, false, no, off, etc.).⁠[3]

 

In YAML:

  • Indentation matters.

  • Tabs are not allowed.[4]

  • A line or fragment of a line that begins with an unquoted hash (#) is a comment and is ignored.

 

References

Endnotes


1. Many Infinite Ink articles, including this one, are evergreen and regularly updated.
2. I like to think that the AML part of YAML stands for Atoms, Maps, and Lists, but this is not what the YAML acronym really stands for.
3. I learned about the off problem the hard way. Here is a story about someone who learned about the no problem the hard way: The Norway Problem.
4. Tabs are allowed in some parts of a YAML serialization, but it is safest not to use tabs at all.

Comments 👍 👎 📝

Please comment so I know I'm not speaking into the void. Also, your public comment might improve this page or help me to improve this page.