What is YAML?
YAML is a data format designed to be easy for humans to read and write. It uses indentation (like Python) instead of brackets (like JSON) to show structure.
yaml
# A simple configuration
name: My Application
version: 2.1.0
database:
host: localhost
port: 5432
credentials:
username: admin
password: secret
features:
- authentication
- caching
- logging
The same data in JSON would need quotes, brackets, and commas everywhere. YAML trades that for whitespace sensitivity.
Basic Syntax
| Type | YAML | JSON Equivalent |
|---|---|---|
| String | name: hello | {"name": "hello"} |
| Number | count: 42 | {"count": 42} |
| Boolean | enabled: true | {"enabled": true} |
| Null | value: null or value: ~ | {"value": null} |
| Array | - item1- item2 | ["item1", "item2"] |
| Object | key: nested: value | {"key": {"nested": "value"}} |
Where You'll See This
- Docker Compose -
docker-compose.yml - Kubernetes - All resource definitions
- GitHub Actions -
.github/workflows/*.yml - CI/CD - GitLab CI, CircleCI, Travis
- Ansible - Playbooks and configs
- Swagger/OpenAPI - API specifications
- Hugo/Jekyll - Static site configs
Common Patterns
Multi-line Strings
yaml
# Literal block (preserves newlines)
description: |
This is a long description
that spans multiple lines.
Each newline is preserved.
# Folded block (joins lines)
summary: >
This will all become
one long line with
spaces between.
Anchors and Aliases
yaml
# Define once, reuse many times
defaults: &defaults
adapter: postgres
host: localhost
development:
<<: *defaults
database: dev_db
production:
<<: *defaults
database: prod_db
Inline Syntax
yaml
# Arrays
colors: [red, green, blue]
# Objects
point: {x: 10, y: 20}
Common Gotchas
⚠️The Norway Problem
YAML interprets certain values as booleans. The country code NO becomes false. Always quote ambiguous strings: country: "NO"
- Indentation matters - Use spaces, not tabs. Inconsistent indentation breaks everything.
- Implicit typing -
yes,no,on,offbecome booleans. Quote them if you mean strings. - Colon in strings -
title: Hello: Worldfails. Use quotes:title: "Hello: World" - Numbers with leading zeros -
version: 0.10might become0.1. Quote version numbers. - Date strings -
date: 2024-01-31becomes a Date object. Quote if you want a string.
Values That Become Booleans
yaml
# All of these become true:
enabled: yes
enabled: Yes
enabled: YES
enabled: on
enabled: true
# All of these become false:
disabled: no
disabled: No
disabled: NO
disabled: off
disabled: false
# To keep as strings, quote them:
answer: "yes"
country: "NO"
YAML vs JSON
| YAML | JSON | |
|---|---|---|
| Readability | Very human-readable | More verbose |
| Comments | Supported (#) | Not supported |
| Size | Smaller (no quotes, brackets) | Larger |
| Parsing | Slower, complex | Fast, simple |
| Whitespace | Significant (dangerous) | Insignificant |
| Best for | Config files | Data interchange |
In Code
javascript
// Node.js with js-yaml
const yaml = require('js-yaml');
// Parse YAML string
const data = yaml.load(`
name: app
version: 1.0
`);
// Convert to YAML string
const yamlString = yaml.dump({ name: 'app', version: 1.0 });
python
# Python with PyYAML
import yaml
# Parse YAML
with open('config.yml') as f:
data = yaml.safe_load(f)
# Write YAML
with open('output.yml', 'w') as f:
yaml.dump(data, f)
Try It
Validate YAML"YAML: Making configuration readable since 2001, and debugging whitespace errors since 2002."