Learning YAML Step by Step

7 min read · Beginner

You will learn

The YAML colon-space rule: key: value
The four basic data types: string, number, boolean, null
How to spot and fix the most common beginner mistakes

Don’t Worry, YAML is Easy

In this lesson, we’ll learn how to write YAML files. Think of YAML like writing a very organized shopping list or recipe. There are just a few simple rules to follow.

The Most Important Rule: Spaces Matter

The most important thing to remember about YAML is that spaces matter. Just like when you write an outline for an essay, you use indentation to show which items belong together.

Important: Always use the space bar, never use the Tab key!

Rule 1: Writing Simple Information (Key-Value Pairs)

The simplest way to store information in YAML is like this:

name: "My Semiconductor Design"

speed: 100

designer: "John Smith"

This is like saying:

The name is “My Semiconductor Design”
The speed is 100
The designer is “John Smith”

Remember: Always put a space after the colon (:)

Watch how each pair is built, piece by piece — the key (label), the colon, the mandatory space, and the value:

Interactive: Anatomy of a YAML Pair

Watch three lines being built — each part is color-coded and explained

chip_name: "My Processor"

frequency: 100

debug_mode: true

The YAML will build up on the left, piece by piece. Each colored part is explained here.

Rule 2: Adding Comments (Notes to Yourself)

You can add comments (notes) to your YAML file using the # symbol. Comments are ignored by computers but help humans understand the file:

# This is my first YAML file

project_name: "Simple Semiconductor Design"

speed: 50 # Speed in MHz

power: 2 # Power in watts

Comments are like sticky notes — they help you remember what each setting does.

Rule 3: Different Types of Information

YAML can handle different types of information. Click the tabs below to explore each type:

Interactive — YAML data types

chip_name:"My Awesome Processor"

designer_name:"Alice Johnson"

family:"Cyclone V"

Use quotes for text, especially with spaces or special characters

Text (Strings)

chip_name: "My Awesome Processor"

designer_name: "Alice Johnson"

Numbers

frequency: 100 # A whole number

voltage: 1.2 # A decimal number

temperature: -25 # A negative number

True or False (Booleans)

debug_mode: true # Yes, turn on debug mode

testing_done: false # No, testing is not done

power_saving: yes # Another way to say "true"

error_checking: no # Another way to say "false"

Your First Complete YAML File

Let’s put it all together and create a simple semiconductor design configuration. Watch it being built line by line — click any line to read what it does:

Interactive: Building a YAML File Line by Line

Click Next to add lines — click any line to read what it does in plain English

# My First Semiconductor Design

project_name: "Learning Processor"

version: "1.0"

date_created: "2024-01-15"

# Technical specifications

frequency_mhz: 100

voltage_volts: 1.2

low_power_mode: true

Click Next to start building the file. Each line is explained here.

Here is the complete file with all sections. Notice the dots showing indentation — 2 dots for items inside a group:

# My First Semiconductor Design Configuration File

# Created by: [Your Name]

# Basic project information

project_name: "Learning Processor"

version: "1.0"

date_created: "2024-01-15"

# Technical specifications

specifications:

·· frequency_mhz: 100

·· voltage_volts: 1.2

·· temperature_celsius: 25

·· low_power_mode: true

# List of features to include

features:

·· - "basic_arithmetic"

·· - "memory_access"

·· - "interrupt_handling"

# Team information

team:

·· lead_designer: "Your Name"

·· reviewer: "Senior Engineer"

·· project_manager: "Team Lead"

· = one space

Understanding Indentation (The Space Rule)

Look at this example carefully — count the dots at the start of each line:

chip_design: # Top level (no spaces)

·· name: "My Chip" # 2 spaces

·· speed: 100 # 2 spaces

·· details: # 2 spaces

···· size: "small" # 4 spaces

···· power: "low" # 4 spaces

· = one space

Think of it like this family tree:

chip_design (grandparent — 0 spaces)
- name (child — 2 spaces)
- speed (child — 2 spaces)
- details (child — 2 spaces)
  - size (grandchild — 4 spaces)
  - power (grandchild — 4 spaces)

Common Beginner Mistakes (And How to Avoid Them)

Click through each mistake — see the error highlighted in red on the left, then click “Show Fix” to see the corrected version slide in on the right:

Interactive: Common Beginner Mistakes

See each mistake, spot the error, then click "Show Fix" to see the correction

1 / 3 Mistake 1: Forgetting Spaces

✗ WRONG

# WRONG - No space after colon

name:"My Processor" no space!

✓ RIGHT

Click "Show Fix" to reveal →

YAML requires a space after every colon. Without it, YAML cannot tell where the key ends and the value begins. This is the #1 most common mistake.

Key takeaways

Congratulations! You now know the basic rules of YAML:

Key-value pairs: Use name: value format
Comments: Use # for notes
Indentation: Use spaces (not tabs) to show relationships
Lists: Use - to make bullet points
Data types: Text, numbers, and true/false values

These simple rules are all you need to start writing YAML files. In the next lesson, we’ll learn how to organize more complex information using these same basic rules.

← Previous Next: Organizing with Nesting →