YAML Basics

What is YAML?

YAML Ain’t Markup Language (YAML) is a human-readable data serialization format that is commonly used for configuration files and data exchange.

YAML Document Structure

A YAML document consists of one or more YAML nodes, which can be scalars, sequences, or mappings. Each node is represented by a key-value pair, where the key is separated from the value by a colon and a space. The key-value pair is indented to indicate the nesting level.

YAML Nodes

A YAML node is a single data item in a YAML document and can be one of the following types:

• Scalar: A single value, such as a string, number, or boolean. Also known as literals.
• Sequence: An ordered list of values. Also known as an array or list.
• Mapping: A collection of key-value pairs. Also known as an object or dictionary.

Scalar Node Example:

name: John Doe #string [scalar]
age: 30 #number [scalar]
is_student: false #boolean [scalar]

Sequence Node Examples:

fruits: #sequence [array]
  - apple #string [literal]
  - banana #string [literal]
  - orange #string [literal]

or

fruits: [apple, banana, orange] #sequence [array]

Remember that the order matters with sequences but not with mappings.

Mapping Node Example:

person: #mapping [object]
  name: John Doe #string [literal]
  age: 30 #number [literal]
  is_student: false #boolean [literal]

Putting it all together:

You can mix and match these node types to create complex data structures in YAML. The following example is a combination of scalar, sequence, and mapping nodes:

person:
  name: John Doe #string [literal]
  age: 30 #number [literal]
  is_student: false #boolean [literal]
  hobbies: #sequence [array]
    - reading #string [literal]
    - hiking #string [literal]
  address: #mapping [object]
    street: 123 Main St #string [literal]
    city: Anytown #string [literal]
    state: NY #string [literal]
    zip: 12345 #string [literal]

In this example, the person node is a mapping that contains scalar nodes for name, age, and is_student, a sequence node for hobbies, and another mapping node for address.

Indentation

Indentation is crucial in YAML to define the structure of the data. The number of spaces used for indentation is not fixed but must be consistent throughout the document. The most common indentation style is two spaces, but four spaces and tabs are also used.

Here is an example of indentation in a YAML document:

example:  #indention level 1
  - person:  #indention level 2 (2 spaces deep)
      name: "Jamey" #indentationlevel 3 (4 spaces deep)
      type: "awesome" #indentation level 3 (4 spaces deep)

Multi-line Strings

YAML supports multi-line strings using the | character followed by a newline. This allows you to write long strings without worrying about indentation.

description: |
  This is a multi-line
  string in YAML

Comments

Comments in YAML start with a # symbol and can be placed at the end of a line or on a separate line. Comments are ignored by the YAML parser and are used to provide additional information or context to the data.

# This is a comment
name: John Doe # This is another comment

YAML Parsers

To validate and format YAML data, you can use online parsers. My favorite online YAML parser is codebeautify.org

Conclusion

YAML is used in many applications and systems due to its human-readable format and flexibility. Understanding the basic structure of YAML documents and nodes is essential for working with YAML files effectively. Good luck!