In this tutorial, you will learn the fundamentals of YAML, a data serialization format designed to be easily readable by humans. Widely used in configuration files, data exchange, and many other areas, YAML is intuitive and seamlessly integrates with various programming languages, making it a versatile and essential tool.

YAML basic rules

  • YAML is a superset of JSON
  • YAML is case sensitive
  • YAML does not allow the use of tabs; spaces are allowed instead
  • Must be space between the element parts
  • Use .yaml or .yml extension for your YAML file

Basic Syntax

Key-value pairs

In YAML, data is represented as key-value pairs:

name: John Doe
age: 30

Lists

Lists in YAML are represented with dashes (-):

fruits:
  - Apple
  - Banana
  - Cherry

The inline format represents the list with items separated by a comma and space and enclosed within square brackets ([]), resembling JSON array syntax.

fruits: [Apple, Banana, Cherry]

Nested Objects

YAML uses indentation to represent nested structures. A common practice is to use 2 spaces for each level of indentation:

person:
  name: John Doe
  age: 30
  address:
    street: 123 Main St
    city: Example City

Comments

You can add comments in YAML with the # symbol. Comments are ignored by the YAML parser:

# This is a comment

Data types in YAML

YAML supports several data types:

n1: 1                  # integer          
n2: 1.234              # float      

s1: 'A Developer'      # string        
s2: "A Developer"      # string           
s3: A Developer        # string           

b: false               # boolean type 

d: 1982-10-14          # date type

nil: null

Advanced Features

Multi-line strings

YAML offers two ways to handle multi-line strings: using the | or > operator.

  • |: Preserves newlines.
description: |
  This is a description
  that spans multiple lines.
  • >: Converts newlines to spaces.
description: >
  This is a description
  that will be joined into a single line.

Key quoting rules

Explain when and why keys need to be quoted. YAML requires quoting for special characters or spaces in keys.

"key with spaces": value
"key:with:special:characters": value

Advanced list representations

YAML allows complex data structures within lists, such as lists of objects or nested lists.

List of objects

products:
  - name: Laptop
    price: 999.99
    in_stock: true
  - name: Mouse
    price: 25.50
    in_stock: false

Nested lists

matrix:
  - [1, 2, 3]
  - [4, 5, 6]
  - [7, 8, 9]

References

YAML allows references to reuse parts of data. This is helpful when you need to reference the same value multiple times:

defaults: &defaults  # Define an anchor named "defaults"
  color: red
  size: medium

item1:
  <<: *defaults      # (*) is a reference to a previously defined anchor value
  name: T-shirt

item2:
  <<: *defaults
  name: Hoodie

Explicit data types

Although YAML often infers types automatically, you can explicitly declare data types using tags.

string: !!str 42         # Force to string
integer: !!int "42"      # Force to integer
float: !!float "3.14"    # Force to float
boolean: !!bool "true"   # Force to boolean

Custom tags

Custom tags are used to define domain-specific data or include special metadata.

user:
  name: John Doe
  address: !address
    street: 123 Main St
    city: Example City
    postal_code: 12345
    country: Exampleland

In this example, !address is a custom tag indicating that the address data should be treated with specific logic, such as validation or formatting, based on the tag.

Document separators

YAML supports multiple documents within a single file, separated by ---.

---
person:
  name: John
  age: 30
---
person:
  name: Jane
  age: 25

Environment variables

You can embed environment variables in YAML files using placeholders.

database:
  host: ${DB_HOST}
  port: ${DB_PORT}