YAML Tutorial for Beginners: Syntax, Examples & Tips

YAML is the configuration language of modern DevOps. Kubernetes, Docker Compose, GitHub Actions, Ansible — they all use YAML. If you're new to it, this guide takes you from zero to confident in one read.

What is YAML?

YAML (YAML Ain't Markup Language) is a human-readable data serialization format. Unlike JSON, it uses indentation instead of braces and brackets to define structure. The design goal is a format that is easy for humans to read and write.

Basic syntax: key-value pairs

# This is a comment
name: Alice
age: 28
active: true
score: 95.5
empty_value: null   # or ~

No quotes needed for simple values. No commas. No braces.

Strings

simple: Hello World           # no quotes needed
with_colon: "key: value"      # quote if contains special chars
single: 'It''s a string'      # single quote escapes with ''
multiline_folded: >            # > folds newlines into spaces
  This is a long
  string that becomes
  one line.
multiline_literal: |           # | preserves newlines exactly
  Line one
  Line two
  Line three

Lists (sequences)

fruits:
  - apple
  - banana
  - cherry

# Inline list
colors: [red, green, blue]

# List of objects
users:
  - name: Alice
    age: 28
  - name: Bob
    age: 34

Nested maps (objects)

server:
  host: localhost
  port: 8080
  ssl:
    enabled: true
    cert: /etc/ssl/cert.pem

# Inline map
point: {x: 10, y: 20}

Anchors and aliases (reuse values)

# Define an anchor with &
defaults: &defaults
  timeout: 30
  retries: 3

# Reuse it with *
production:
  <<: *defaults      # merge all keys from defaults
  host: prod.example.com

staging:
  <<: *defaults
  host: staging.example.com

Real Kubernetes example

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.25
          ports:
            - containerPort: 80
          resources:
            requests:
              memory: "64Mi"
              cpu: "250m"
            limits:
              memory: "128Mi"
              cpu: "500m"

Real GitHub Actions example

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install
        run: npm install
      - name: Build
        run: npm run build
      - name: Deploy
        run: npm run deploy
        env:
          API_KEY: ${{ secrets.API_KEY }}

Common YAML mistakes

• Using tabs for indentation — YAML forbids tabs. Use spaces only.
• Inconsistent indentation — always use the same number of spaces per level (2 is standard).
• Forgetting to quote special strings — values like yes, no, true, false, null, 1.0 get auto-typed. Quote them if you mean a string: "yes".
• Colons in strings — url: http://example.com breaks. Quote it: url: "http://example.com".