YAML (YAML Ain't Markup Language)

What it looks like

# A Kubernetes-style config
name: web
replicas: 3
ports:
  - 80
  - 443
env:
  DEBUG: "false"
  GREETING: |
    Hello,
    world

Indentation (spaces only, never tabs) shows nesting. key: value lines make a mapping, - item lines make a list, and # starts a comment. Strings usually need no quotes, and | or > start multi-line text. The same data can also be written in JSON-like flow style: ports: [80, 443].

How it relates to JSON

YAML 1.2 is a superset of JSON: every JSON document is valid YAML. YAML adds comments, anchors and aliases (&name and *name) for reusing a block, merge keys (<<) for combining mappings, custom tags such as CloudFormation’s !Ref, and several documents in one file separated by ---. None of those have a JSON equivalent, so converting YAML to JSON drops or expands them, while converting JSON to YAML loses nothing.

Pitfalls

• Unquoted values that change type. Under YAML 1.1 rules, still used by PyYAML, SnakeYAML and Ruby, NO, yes, on and off are booleans, 0755 is octal 493 and 1:20 is 80. This is the “Norway problem”: a list of country codes turns NO into false. YAML 1.2 reads them as strings or ordinary numbers, so the same file differs between tools. Quote them.
• Numbers that lose digits. 3.10 is the number 3.1, a classic bug in CI files that list Python versions. Quote version numbers.
• Indentation errors. A mis-indented line silently moves a key into a different mapping rather than causing an error. Tabs are not allowed for indentation at all.
• Duplicate keys. The spec forbids them, but many parsers keep the last one without complaint, so a repeated key can quietly override an earlier setting.