Last updated
Why YAML Formatting Matters
YAML (YAML Ain't Markup Language) is a human-readable data serialization format widely used for configuration files in Docker Compose, Kubernetes, GitHub Actions, Ansible, and many other tools. Unlike JSON, YAML uses indentation to define structure — which means a single misplaced space can silently break your entire configuration or cause a hard-to-debug parse error.
A YAML formatter normalizes indentation, removes trailing whitespace, and ensures consistent spacing around colons and dashes. This is especially important in CI/CD pipelines where malformed YAML causes cryptic deployment failures.
YAML Syntax Quick Reference
| Construct | Syntax | Notes |
|---|---|---|
| Key-value pair | key: value | Space after colon is required |
| Nested object | parent:
child: val | 2-space indent is conventional |
| List item | - item | Dash followed by space |
| Multiline string | key: | | Literal block scalar, preserves newlines |
| Folded string | key: > | Folds newlines into spaces |
| Comment | # comment | Hash to end of line |
| Null value | key: ~ or key: | Both represent null |
| Boolean | true / false | Lowercase only in YAML 1.2 |
Common YAML Mistakes
- Tabs instead of spaces: YAML explicitly forbids tab characters for indentation. Always use spaces.
- Inconsistent indentation: Mixing 2-space and 4-space indentation within the same file causes parse errors.
- Unquoted special values: Values like
yes,no,on,offare parsed as booleans in YAML 1.1. Quote them if you mean the string. - Colon in values: A colon followed by a space in an unquoted value starts a new key. Use quotes:
url: "http://example.com". - Duplicate keys: YAML allows duplicate keys but behavior is undefined — most parsers use the last value silently.
Kubernetes Example
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
labels:
app: my-app
spec:
replicas: 3
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: my-app
image: my-app:1.0.0
ports:
- containerPort: 8080
env:
- name: DATABASE_URL
valueFrom:
secretKeyRef:
name: db-secret
key: urlValidating YAML in CI/CD
For automated validation, use yamllint (Python) or yq (Go).
Both can be added to GitHub Actions or GitLab CI to catch formatting issues before deployment:
# Install yamllint
pip install yamllint
# Validate a file
yamllint docker-compose.yml
# Validate all YAML files in a directory
yamllint .github/workflows/