YAML Includes Atoms, Maps, and Lists
Updated 2021-March-28

Page contents

News

2020-November-10  As of today, this evolving⁠[1] article has been on the web for one 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. 2 or 2.718281828),

  • or a string (e.g. hello world).

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.

 

Examples

Here is a YAML fragment that is discussed in section 2 of Infinite Ink’s Intertwingling AsciiDoc and Hugo⁠:

markup:
 asciidocExt:
  preserveTOC: true
  workingFolderCurrent: false  # default is false
  attributes:
   toc: macro
   hide-uri-scheme: true@  # trailing @ means ok to override
   sectlinks: true
   ii2do-title: Infinite Ink’s To-Do and Done Lists
   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/

 

Note that in the above example, I indent each level with only a single space. I do this because I’m hoping to prevent line wrapping when this page is displayed on a small screen.

For more YAML examples, see Infinite Ink’s…

 

Syntax tips

In general, you do not need to use quotation marks around YAML strings. Quoting a string is required if it…

  • includes a hash (#), greater than (>), or any character that has a special meaning in YAML;

  • 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 unquoted fragment that begins with a 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’s 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 & reactions 👍 👎 📝

To comment or react, you must be signed in to GitHub.