YAML Quickstart

YAML, which stands for YAML Ain't Markup Language (a recursive acronym), is a human-readable data serialization standard. It is commonly used for configuration files and data exchange between languages with different data structures.

YAML is a good alternative to configuration stored in code or some old formats, like *.ini files (anyone still remembers that?).

What is YAML?

At its core, YAML is designed to be readable and writable by humans. It's often used in scenarios where data is being stored or transmitted without the need for a markup language. YAML is a superset of JSON, meaning JSON files are also valid YAML files, but YAML offers a more human-friendly syntax.

YAML Syntax Essentials

YAML is sensitive to indentation (like Python), employing spaces (not tabs) to nest elements. This design choice simplifies the structure, making it visually clear and easy to read.

Comments

Comments in YAML start with a # symbol. Anything following this symbol on the line is ignored by the parser.

# This is a comment
key: value # This is an inline comment

Scalars, Sequences, and Mappings

• Scalars: Simple, singular values like strings, numbers, or booleans.
• Sequences: Lists or arrays, denoted by a dash (-).
• Mappings: Key-value pairs, similar to dictionaries or objects in other languages.

Strings

Strings in YAML don't necessarily require quotation marks, but they can be used to ensure special characters are interpreted correctly.

plain: This is a plain string.
double_quoted: "Includes special characters: \n, \t, etc."
single_quoted: 'In single quotes, special characters like \n are just plain text.'

Multiline Strings

YAML offers block notation for multiline strings:

• | for keeping line breaks
• > for folding line breaks (turning them into spaces)

keep_newlines: |
  This string contains
  multiple lines with
  newlines preserved.

fold_newlines: >
  This string also contains
  multiple lines, but newlines
  will be folded into spaces.

Lists (Sequences)

Lists are created with a hyphen and a space before each item:

fruits:
  - Apple
  - Banana
  - Orange

Dictionaries (Mappings)

Dictionaries are a set of key-value pairs:

person:
  name: John Doe
  age: 30

Nested Structures

You can nest lists and dictionaries to create complex structures:

people:
  - name: John Doe
    age: 30
    hobbies:
      - Hiking
      - Reading
  - name: Jane Smith
    age: 25
    hobbies:
      - Cycling
      - Painting

Anchors and Aliases

YAML allows you to define reusable anchors (&) and reference them later with aliases (*), reducing repetition:

defaults: &defaults
  editor: vscode
  license: MIT

projectA:
  <<: *defaults
  language: Python

projectB:
  <<: *defaults
  language: JavaScript

Some Tips

• Indentation: Always use spaces, not tabs, for indentation. The standard practice is two spaces.
• Quotation Marks: Use them to wrap strings that contain special characters or leading/trailing spaces.
• Readability: Favor readability over compactness. YAML is designed to be easy to read and understand at a glance.