Yaml

At its conception yaml was given its name based the following acronym:

Y: Yet
A: Another
M: Markup
L: Language

Although quickly the developers came to the conclusion that yaml was so much more than a markup language and was instead more like a data serialization language so deciding that they didn't want to buy another domain since they already owned https://yaml.org, they gave it the rather humorous acronym:

Y: Yaml
A: Ain't
M: Markup
L: Language

Other than being a recursive acronym it also really sells the point of how powerful yaml truly is. So if yaml ain't a markup language what is it? I still consider yaml to be a markup language and so does most of the rest of the world but it definitely sets itself apart for other markup languages with its syntax. Let's look at an excerpt from the yaml Website:

"YAML™ (rhymes with “camel”) is a human-friendly, cross language, Unicode based data serialization language designed around the common native data structures of agile programming languages. It is broadly useful for programming needs ranging from configuration files to Internet messaging to object persistence to data auditing."

How to yaml

Let's stop talking and to the basics. Let's start by taking a look at an example yaml file:

---
john: "Lennon"
paul: "Sir MacCartney"
george: Harrison
ringo: Star
members: 4
inspirational: true
albums:
  - revolver
  - help
  - white
  - "abbey road"
instruments:
  bass-guitar: true
  drums: true
  guitar: true
  number-of-instruments:
    bass: 1
    drums: 1
    guitars: 2
  left-handed:
    Paul: true

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-deployment
  labels:
    env: production
spec:
  selector:
    matchLabels:
      app: myapp
  replicas: 6
  template:
    metadata:
      name: nginx-2
      labels:
        app: myapp
    spec:
      containers:
        - name: nginx
          image: nginx

Yaml allows us to define multiple documents in a single file. Each document starts with ---. The next thing we see is a construct that makes up most of the yaml syntax: the key/value pair. john is a key and "Lennon" is a string value for this key. Yaml supports more data types than strings though we can see that members is an integer and inspirational is a boolean. Yaml also supports floating point numbers ie: 3.14159. Strings can be noted with single quotes, double quotes, or no quotes at all like in the case of the key george. Yaml is also smart enough to note integers and floating point numbers without quotes. The albums key has four elements assigned to it, each of these is denoted with a -. Indentation in yaml is very important so to note that these elements are part of the albums key they are all indented with two spaces. The number of spaces can vary from file to file but yaml will not support tabs and two spaces is the most common indentation so it is wise to follow standards. Finally we see the instruments key which we can think of as a dictionary, containing three booleans and two nested dictionaries. Yaml supports nesting of key/value pairs, and mixing types.

If you have experience with json you may notice that the layout and concepts of yaml is very similar, just with less curly braces. In fact you can convert most yaml documents to json and vice versa. Here is a helpful link if converting from json to yaml interests you: json2yaml.

Indentation and Whitespace

Whitespace is a very important part of yaml's formatting. Unless otherwise indicated, newlines indicate the end of a field. Yaml uses indentation to determine what key your entry belongs to. Like shown above it is most common to indent with two spaces when denoting a list of values for a key or building a dictionary for a key although indentation just has to be one or more spaces. Yaml does not support tabs for its indentation as some languages or tools handle tabs differently.

Comments

In yaml comments are denoted with a pound sign: #. Comments can appear at the end of a line or at the beginning specifying the entire line as a comment. Let's look at an example:

---
# This is a comment
foo: bar # So is this though

Although there is no requirement for it; it is most common to leave a space before and after the pound sign for easy readability so it is a good habit to get into.

Yaml Datatypes

We briefly covered it up above but let's go over the specifics of what data types yaml supports:

Key/Value Pairs and Dictionaries

The Key/Value pair is yaml's basic building blocks. Every item in a yaml document is a member of at least one dictionary, whether that be a dictionary defined in the document or the document itself. The key of a Key/Value pair is always a string, however the value is a scalar and can be any data types support by yaml. We have already seen the value being set as a string, number, boolean, or another dictionary.

Numeric Types

Yaml recognizes many common numeric types and even some not so common numeric types. The first of these numeric types are Integer types. We have seen some examples above but let's look at what Integer types are supported:

---
foo: 231234
bar: 0xDE23
plop: 023332

We can see that foo is just a standard decimal number, however bar is a hexadecimal number (denoted by the 0x) and plop is an octal number (denoted by the 0 at the beginning).

The next numeric type that yaml supports is the floating point numbers. Yaml supports both fixed and exponential floating point numbers:

---
foo: 3.14159
bar: 24.6701e+05

The less common numeric types yaml supports is infinity and not-a-number or NAN as it is referred:

---
foo: .inf
bar: -.inf
plop: .NAN

In our example we can see that foo is given a value of infinity whereas bar is given a value of negative infinity. Finally we assign plop a value of NAN.

Strings

Yaml handles strings very well and in most situations you don't have to specify single or double quotes, however if you want escape sequences handled we need to use double quotes:

---
foo: "This string has an escape squence\n"
# Will be read as "This string has an escape squence"

bar: This string has a\n
# Will be read as "This string has a\n"

plop: 'This string has a\n'
# Will be read as "This string has a\n"

Yaml will not escape strings with single quotes either as we can see, but using single quotes will avoid having the string contents interpreted as document formatting. Strings values can also span multiple lines with the fold (>) character:

---
foo: >-
  This string spans
  multiple lines.
  I can write stories
  with this.

With fold however the block will not be interpreted with the newline characters making it all one string. If you want to keep the formatting you can use the pipe (|) character, which behaves very similar to the fold character but interprets the field exactly as it is:

---
bar: |
  Now I can really
  type my story.
  This will keep its
  formatting exactly
  as it is displayed!

Nulls

If you every need to assign a null value to a key you yaml supports that as well. You can specify a null value with either a tilde (~) or the unquoted string null:

---
foo: ~
bar: null

Booleans

In yaml you specify boolean values with keywords with True, true, On, on, Yes, or yes to represent true and False, false, Off, off, No, or no to represent false:

---
foo: True
bar: False
light: On
tv: no

Arrays

You can specify arrays in yaml on a single line or with a list:

---
items: [ 1, 2, 3, 4, 5]
numbers:
  - 1
  - 2
  - 3
  - 4
  - 5

The list format is useful when your list contains complex objects instead of scalar values:

___
items:
  - things:
      thing1: huey
      things2: dewey
      thing3: louie
  - other things:
      key: value

An array can contain any valid yaml value. The values in a list do not have to be the same type either.

Dictionaries

We briefly covered dictionaries previously, but there is more to them. Like arrays, you can put dictionaries inline:

---
foo: { thing1: huey, thing2: louie, thing3: dewey }

Dictionaries can span multiple lines:

---
foo: bar
bar: foo

Dictionaries can of course also be nested:

---
foo:
  bar:
    - bar
    - rab
    - plop