YAML in depth

Why learn YAML properly

YAML (it stands for "YAML Ain't Markup Language") is the configuration format of Kubernetes, Docker Compose, GitHub Actions, GitLab CI and Ansible. A DevOps engineer reads and writes YAML every day. It looks simple, and that is the trap: one wrong space can change the meaning of a file or stop a deployment.

Scalars, maps and lists

A scalar is a single value: a string, a number, a boolean (true or false) or null (no value). A map (also called a dictionary or mapping) is a set of key: value pairs. There must be a space after the colon. A list (also called a sequence) is a set of items, each on its own line starting with a dash and a space.

# a comment starts with #
name: college-portal        # string
replicas: 3                 # integer
price: 49.5                 # float
debug: false                # boolean
owner: null                 # null (~ also means null)
ports:                      # a list
  - 80
  - 443
database:                   # a nested map
  host: db.internal
  port: 5432

Lists and maps can nest inside each other. A list of maps is very common, for example a list of containers in Kubernetes or a list of tasks in Ansible. Short forms also exist: [80, 443] for a list and {host: db, port: 5432} for a map. This is called flow style, and it looks like JSON.

users:
  - name: asha
    shell: /bin/bash
  - name: ravi
    shell: /bin/zsh
tags: [web, prod]            # flow style list

Indentation rules

YAML allows only spaces for indentation. Tabs are not allowed. Two spaces per level is the usual style. The exact number does not matter, but all items at the same level must have the same indentation, and a child must be indented more than its parent.

Quoting strings

Most strings need no quotes. Use quotes when the text could be misread. Single quotes take the text literally (write two single quotes to include one). Double quotes allow escapes such as \n for a new line.

country: "NO"               # without quotes, a YAML 1.1 parser reads this as false
version: "1.10"            # without quotes, this is the float 1.1
message: "Error: disk full" # a colon followed by a space inside plain text breaks parsing
colour: "#ff6600"          # without quotes, # starts a comment and the value is null
mode: "0644"               # without quotes, some parsers read 0644 as an octal number
greeting: 'It''s ready'    # two single quotes make one apostrophe

The Norway problem

YAML 1.1, the older version still used by many parsers (including PyYAML, which Ansible uses), treats yes, no, on, off, y and n (in several capitalisations) as booleans. So a list of country codes with NO for Norway becomes false. YAML 1.2 fixed this: in its core schema only true and false are booleans. Because you rarely know which version a tool uses, quote any string that looks like a boolean, a number, a date or null.

Multi-line strings

script: |
  echo "line one"
  echo "line two"
description: >
  This long sentence is folded
  into a single line with spaces.

Add a minus sign (|- or >-) to remove the final new line. Indent the text block more than its key.

Anchors and aliases

An anchor (&name) labels a value, and an alias (*name) reuses it, so you do not repeat yourself. Many tools also support the merge key <<, which copies a map into another one. The merge key comes from YAML 1.1 and is not part of the YAML 1.2 core, so check that your tool supports it.

defaults: &defaults
  restart: always
  log_level: info
web:
  <<: *defaults
  port: 8080
worker:
  <<: *defaults
  log_level: debug   # overrides the copied value

Many documents in one file

Three dashes (---) start a new document. Kubernetes uses this to keep a Deployment and a Service in one file. A file may also start with --- even if it has only one document; Ansible playbooks often do.

YAML and JSON

JSON is almost a subset of YAML 1.2: nearly every JSON file is also valid YAML. That is why flow style looks like JSON. The reverse is not true: comments, anchors and indentation-based nesting do not exist in JSON.

Common mistakes

• A tab used for indentation: error "found character that cannot start any token". Set your editor to insert spaces for YAML.
• Inconsistent indentation: a key indented by 3 spaces under siblings at 2 becomes a parse error or, worse, a different structure.
• Forgetting the space after a colon or a dash: key:value is a plain string, not a map.
• Unquoted special values: NO, yes, on, 1.10, 0644, 2026-10-19 (a date), ~ (null).
• A colon and space, or a #, inside an unquoted value.