A Complete, Non-Boring Guide To Learn YAML In 2025
YAML (YAML Ain’t Markup Language) has become the backbone of modern DevOps tooling. From Kubernetes to GitHub Actions, mastering YAML is essential for anyone working in technology today. In this guide, I’ll walk you through YAML’s core concepts using familiar examples that will make learning both enjoyable and practical.
What is YAML?
YAML is a human-readable data serialization language. Unlike JSON or XML, YAML prioritizes readability with a clean, minimal syntax that relies on indentation for structure (similar to Python). It’s designed to be easy for humans to read and write while remaining machine-parsable.
The Basic Building Blocks of YAML
1. Key-Value Pairs
The simplest YAML structure is a key-value pair:
name: John Smith
age: 35
occupation: Software Engineer
Think of these as labels (keys) and the associated information (values).
2. Lists/Arrays
Lists in YAML are created using hyphens:
hobbies:
- Reading
- Hiking
- Photography
- Cooking
Each item starts with a hyphen followed by a space.
3. Nested Structures
YAML shines when representing complex, nested data:
person:
name: Sarah Johnson
age: 28
contact:
email: sarah.j@example.com
phone: 555-123-4567
skills:
- Python
- JavaScript
- Docker
A Family Tree Example
Let’s use a family tree to demonstrate YAML’s power for representing relationships:
family:
name: The Smiths
members:
- name: James Smith
role: Father
age: 42
hobbies:
- Woodworking
- Gardening
- Chess
- name: Maria Smith
role: Mother
age: 40
hobbies:
- Painting
- Running
- Cooking
- name: Emma Smith
role: Daughter
age: 15
hobbies:
- Volleyball
- Piano
- Reading
school: Lincoln High School
- name: Alex Smith
role: Son
age: 10
hobbies:
- Soccer
- Video games
- Science experiments
school: Washington Elementary
pets:
- name: Max
type: Dog
breed: Golden Retriever
age: 5
- name: Whiskers
type: Cat
breed: Maine Coon
age: 3
This structure shows how YAML can organize complex hierarchical data in a way that remains clear and readable.
YAML for Hobbies and Interests Tracking
Let’s explore another example – a hobby tracker:
hobby_tracker:
user: taylor_garcia
categories:
books:
currently_reading:
- title: The Midnight Library
author: Matt Haig
pages: 304
progress: 75%
completed_this_year:
- title: Project Hail Mary
author: Andy Weir
rating: 5
- title: Educated
author: Tara Westover
rating: 4.5
want_to_read:
- Cloud Atlas
- The Three-Body Problem
- Klara and the Sun
fitness:
weekly_goals:
running:
distance_km: 20
current_progress: 12.5
strength_training:
sessions: 3
completed: 2
personal_records:
5k_time: "22:45"
deadlift_kg: 120
cooking:
favorite_recipes:
- name: Vegetable Curry
cuisine: Indian
last_made: "2025-04-12"
- name: Sourdough Bread
cuisine: Artisan
last_made: "2025-04-30"
recipes_to_try:
- Ramen from scratch
- Thai Green Curry
- Homemade Pasta
Important YAML Syntax Rules
1. Indentation Matters
YAML uses indentation (spaces, not tabs) to denote structure. Consistent indentation is crucial:
correct:
nested_key: value
incorrect:
nested_key: value # This will cause errors
2. Colons and Spaces
Always put a space after the colon in key-value pairs:
correct: value
incorrect:value # This will cause errors
3. Quotes for Special Characters
If your text contains special characters, use quotes:
message: "This text has: colons, commas, and other symbols!"
4. Multi-line Strings
YAML offers several ways to handle multi-line text:
Using the pipe character (|) preserves line breaks:
description: |
This is a longer description
that spans multiple lines.
Each line break is preserved.
Using the greater-than symbol (>) folds line breaks into spaces:
description: >
This is a longer description
that spans multiple lines.
Line breaks become spaces.
5. Comments
Comments in YAML start with the # symbol:
# This is a comment
name: John # This is an inline comment
Real-world Applications
Now, let’s look at a more DevOps-focused example – a GitHub Actions workflow:
name: Build and Test Application
# Trigger on push to main branch
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
# Jobs to run
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Set up Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
- name: Install dependencies
run: npm install
- name: Run tests
run: npm test
- name: Build application
run: npm run build
Common Mistakes and How to Avoid Them
1. Inconsistent Indentation
# WRONG
user:
name: John
age: 30 # Incorrect indentation level
Always use consistent indentation (usually 2 spaces).
2. Missing Spaces After Colons
# WRONG
name:John # Missing space after colon
3. Tab Characters
YAML parsers often reject tab characters. Use spaces instead.
4. Unquoted Special Characters
# WRONG
message: Hello: World # The second colon needs to be in quotes
Correct version:
message: "Hello: World"
5. Incorrect List Formatting
# WRONG
hobbies:
- Reading # Missing space after hyphen
Correct version:
hobbies:
- Reading
A Travel Planner Example
Let’s explore one more example – a travel planner:
travel_plans:
destination: Japan
duration_days: 14
travelers:
- name: Emma Wilson
passport: AB123456
dietary_restrictions: Vegetarian
- name: Marcus Wilson
passport: CD789012
dietary_restrictions: None
itinerary:
- day: 1
date: 2025-06-10
location: Tokyo
accommodations:
name: Shibuya Excel Hotel
confirmation: TMY6789
activities:
- time: "14:00"
activity: Check-in at hotel
- time: "16:00"
activity: Explore Shibuya Crossing
- time: "19:00"
activity: Welcome dinner at Ichiran Ramen
reservation: true
confirmation: RMN4532
- day: 2
date: 2025-06-11
location: Tokyo
accommodations:
name: Shibuya Excel Hotel
confirmation: TMY6789
activities:
- time: "09:00"
activity: Tsukiji Outer Market
- time: "13:00"
activity: Meiji Shrine
- time: "16:00"
activity: Harajuku shopping
- time: "20:00"
activity: Dinner at Gonpachi
reservation: true
confirmation: GPC7812
budget:
currency: USD
categories:
flights: 1800
accommodations: 2200
food: 1000
activities: 800
shopping: 500
contingency: 700
total: 7000
packing_list:
documents:
- Passport
- Flight tickets
- Hotel reservations
- Travel insurance
clothing:
- T-shirts: 7
- Pants: 3
- Dresses: 2
- Jackets: 1
- Walking shoes: 1
- Formal shoes: 1
electronics:
- Camera
- Smartphone
- Universal adapter
- Power bank
Validating Your YAML
When working with YAML, it’s important to validate your files. Many online YAML validators are available, and most code editors provide YAML linting extensions.
Common validation errors include:
- Inconsistent indentation
- Missing spaces after colons
- Unquoted special characters
- Improper list formatting
Converting Between YAML and Other Formats
YAML can be easily converted to and from other data formats like JSON. Many online tools and programming libraries support these conversions.
For example, in Python:
import yaml
import json
# Convert YAML to JSON
with open('data.yaml', 'r') as yaml_file:
yaml_data = yaml.safe_load(yaml_file)
json_data = json.dumps(yaml_data)
# Convert JSON to YAML
with open('data.json', 'r') as json_file:
json_data = json.load(json_file)
yaml_data = yaml.dump(json_data)
Conclusion
YAML’s simplicity and readability make it perfect for configuration files and data serialization. By understanding its structure and syntax through these everyday examples, you’ve gained valuable knowledge that applies directly to modern DevOps tools like Kubernetes, Docker, GitHub Actions, and many more.
Remember:
- Indentation defines structure
- Consistency is key
- Use the right syntax for your data type
- Validate your YAML
The more you practice with YAML, the more natural it will become. Start small with simple configurations and gradually work your way up to more complex structures. Before you know it, you’ll be writing YAML with confidence!
Happy coding!
