YAML: A Beginner’s Introduction

YAML (Yet Another Markup Language or YAML Ain’t Markup Language) is a human-readable data serialization standard that’s commonly used for configuration files, data exchange, and storing structured data. It’s designed to be easy to read and write, making it popular for DevOps, applications configuration, and data representation.

Why YAML? Comparing Data Formats

Let’s see how the same data looks in different formats:

XML Format

<person>
    <name>John Doe</name>
    <age>30</age>
    <languages>
        <language>Python</language>
        <language>JavaScript</language>
    </languages>
</person>

JSON Format

{
  "person": {
    "name": "John Doe",
    "age": 30,
    "languages": ["Python", "JavaScript"]
  }
}

YAML Format

person:
  name: John Doe
  age: 30
  languages:
    - Python
    - JavaScript

As you can see, YAML is much cleaner and easier to read! No brackets, braces, or closing tags needed.

Key-Value Pairs in YAML

The foundation of YAML is the key-value pair, separated by a colon and space:

# Basic key-value pairs
name: John Doe
age: 30
city: New York
is_student: false
height: 5.8

Important: Always use a space after the colon!

# ✅ Correct
name: John

# ❌ Wrong
name:John

Arrays/Lists in YAML

Arrays (or lists) are represented using dashes (-). Each dash indicates an element of the array:

# Simple list
fruits:
  - apple
  - banana
  - orange

# Alternative inline format
colors: [red, green, blue]

# List of numbers
scores:
  - 95
  - 87
  - 92

Dictionaries/Maps in YAML

Dictionaries (or maps) are collections of key-value pairs. Indentation is crucial  — all properties of a single item must have the same number of spaces:

# Dictionary example
person:
  name: Alice
  age: 25
  address:
    street: 123 Main St
    city: Boston
    zip: 02101

Visualization of the Dictionary

person:
├─ name: Alice
├─ age: 25
└─ address:
   ├─ street: 123 Main St
   ├─ city: Boston
   └─ zip: 02101

The Power and Danger of Indentation

In YAML, spaces matter! Different indentation levels create different meanings:

Correct Indentation

# All properties at same level (2 spaces)
person:
  name: John
  age: 30
  job: Developer

Incorrect Indentation

# Mixed indentation - This will cause errors!
person:
  name: John
   age: 30 # 3 spaces - WRONG!
  job: Developer # 2 spaces - Different from age

Nested Structure Example

company:
  name: Tech Corp
  employees:
    - name: Alice
      role: Developer
      skills:
        - Python
        - Docker
    - name: Bob
      role: Designer
      skills:
        - Photoshop
        - Figma

Note: In above example you can see that under employees there is a array of dictionaries. ”-” indicates a start of the item.

Dictionary vs List vs List of Dictionaries

Let’s understand the differences with examples:

Simple Dictionary

# A single person
person:
  name: John
  age: 30
  city: NYC

Simple List

# List of names
names:
  - John
  - Alice
  - Bob

List of Dictionaries

# Multiple people (list of dictionaries)
people:
  - name: John
    age: 30
    city: NYC
  - name: Alice
    age: 25
    city: Boston
  - name: Bob
    age: 35
    city: Seattle

Order Matters in Lists, Not in Dictionaries

Dictionaries: Order Doesn’t Matter

These two dictionaries are identical :

# Dictionary 1
person:
  name: John
  age: 30
  city: NYC

# Dictionary 2 - Same as above!
person:
  city: NYC
  name: John
  age: 30

Lists: Order Matters

These two lists are different :

# List 1
fruits:
  - apple
  - banana
  - orange

# List 2 - Different from above!
fruits:
  - banana
  - apple
  - orange

Comments in YAML

Any line starting with # is a comment and is ignored:

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

# Configuration for database
database:
  host: localhost # Local development
  port: 5432
  # password: secret # Commented out for security

Complete Example: Putting It All Together

Here’s a comprehensive YAML example combining all concepts:

# Application Configuration File
app_name: "My Awesome App"
version: 2.1.0
debug: true

# Database configuration
database:
  host: localhost
  port: 5432
  name: myapp_db
  credentials:
    username: admin
    password: secret123
# List of supported languages
languages:
  - English
  - Spanish
  - French
# List of server configurations
servers:
  - name: web-server-1
    ip: 192.168.1.10
    roles:
      - web
      - api
    specs:
      cpu: 4
      memory: 8GB
  - name: db-server-1
    ip: 192.168.1.20
    roles:
      - database
    specs:
      cpu: 8
      memory: 16GB
# Feature flags
features:
  user_registration: true
  email_notifications: false
  premium_features: true

Key Takeaways and Tips

✅ Best Practices

• Always use spaces, never tabs for indentation
• Be consistent with indentation (usually 2 or 4 spaces)
• Use quotes for strings that might be ambiguous
• Add comments to explain complex configurations
• Validate your YAML before using it in production

⚠️ Common Pitfalls

• Mixing tabs and spaces
• Inconsistent indentation levels
• Forgetting the space after colons
• Not quoting strings that start with numbers or special characters

YAML’s simplicity and readability make it an excellent choice for configuration files and data serialization. Remember: indentation is everything in YAML, and when in doubt, validate your syntax!

Happy YAML writing! 🚀