What Is YAML? A Developer's Introduction

Most developers meet YAML before they ever decide to use it. A Kubernetes manifest, a docker-compose.yml, a GitHub Actions workflow, an Ansible playbook — suddenly you are editing a file where whitespace carries meaning and a missing space breaks the deploy. This is the introduction I wish someone had handed me first.

Where YAML shows up whether you asked or not

YAML has become the default serialization format for things that a human is expected to read and edit by hand:

• Kubernetes describes every object — pods, services, deployments — as YAML manifests you apply with kubectl apply -f.
• Docker Compose keeps multi-container setups in a single docker-compose.yml.
• CI pipelines — GitHub Actions, GitLab CI, CircleCI — are almost all YAML.
• Ansible runs playbooks written in YAML.

The reason is consistent: these are configuration files that people open, tweak and review in pull requests. YAML was designed for exactly that audience.

What YAML is actually trying to be

The name originally stood for "Yet Another Markup Language", later repurposed to "YAML Ain't Markup Language" to stress that it is a data format, not a document format. Its stated design goal is simple: be readable by humans first, and parseable by machines second. Where JSON optimises for the parser, YAML optimises for the person squinting at a diff at midnight.

That goal explains every quirk you will meet: the dropped quotes and braces, the significance of indentation, the implicit typing. All of it trades machine-strictness for human comfort.

YAML is a superset of JSON

Any valid JSON document is also valid YAML. Take a JSON blob:

{
  "name": "devtul",
  "replicas": 3,
  "ports": [8080, 8443]
}

The same data in YAML drops the braces, commas and most quotes:

name: devtul
replicas: 3
ports:
  - 8080
  - 8443

Because YAML is a superset, you can paste JSON straight into a YAML file and it will parse. That is handy, but it also means the two formats share the same underlying data model — the differences are almost entirely about syntax.

YAML 1.1 versus 1.2 — why your yes/no behaves differently

This is the single most underestimated source of cross-tool confusion. The spec has two widely deployed versions.

Kubernetes, for example, follows YAML 1.1 semantics through its Go parser, so replicas: off is parsed as the boolean false. A tool built on a 1.2 parser will keep it as the string "off". The same file, two different values, no error. Always quote anything that is not obviously a number or you will be surprised.

The four building blocks

Every YAML document is built from four things:

• Mapping — a key/value collection, written as key: value.
• Sequence — an ordered list, written with - dashes.
• Scalar — a single value: a string, number, boolean or null.
• Comment — anything after #, ignored by the parser.

A mapping whose values are themselves mappings and sequences gives you the nested structure you see in every Kubernetes manifest.

How YAML infers types from symbols and indentation

YAML has almost no keywords. Instead it infers type from context:

count: 3          # integer
ratio: 1.5        # float
flag: true        # boolean
name: devtul      # string
note: "3"         # string, because quoted
empty:            # null
empty2: ~         # also null

This inference is what makes YAML pleasant to write and dangerous to trust. The same line means different things depending on whether you quoted it, how you indented it, and which parser reads it. That is the trade at the heart of the format.

Three traps that bite almost everyone

1. Indentation is not cosmetic

YAML uses indentation to show nesting. Mixing spaces and tabs, or indenting by the "wrong" amount, changes the structure or fails outright. Use two spaces consistently and never a tab.

2. The space after the colon is mandatory

key:value is not a mapping entry — it is the string "key:value". You must write key: value with a space. This is the most common typo in a beginner's first file.

3. yes/no become booleans

An environment variable DEBUG: no is silently the boolean false, not the string "no". Country codes, feature flags and version-ish tokens get swallowed the same way. When in doubt, quote it.

See it parse before you trust it

YAML's biggest risk is that a wrong file often looks right until a tool rejects it at runtime. Before committing, paste your document into the YAML viewer and confirm the parsed structure matches what you intended — especially the booleans and numbers.