What is a YAML file?

YAML is a plain-text format you can open in any editor. It is used for moving data between programs and editing.

The extension is .yaml, and the full name is YAML Ain't Markup Language. Both matter less than what the file can hold, which is what the rest of this page is about.

It dates from 2001. The specification is YAML 1.2.

Age is worth knowing here for one practical reason: the older a format is, the more programs have had time to learn it.

It is published in full, so anyone can implement it from the document rather than by inspection, which is why it turns up in so many programs and why files written twenty years ago still open. A published specification is not the same thing as a royalty-free one: where a format wraps a codec, the patent licensing is a separate question the standard does not settle.

YAML stores its content exactly. Saving it again changes nothing, so it can be opened, edited and re-saved as often as you like without accumulating damage — which is what makes it a working format rather than a delivery one.

YAML has a comment syntax, which is the difference between a file a person maintains and one a program writes. Comments are the first thing lost converting to a format without them, and nothing warns you.

Visual Studio Code and yq read it, and so do most programs of the same kind.

If a file will not open, the format is rarely the problem — it is more often that the program predates it. Converting to something older is the reliable way past that, and it is what the rest of this site is for.

No browser reads it.

That is the single most common reason to convert it: not that the format is bad, but that the place you want to show the file cannot read it.

YAML is meant to be opened and changed. Keep the file in this format for as long as the work is going on, and export from it whenever a finished copy is needed.

Very few people pick YAML. They are handed it: Kubernetes manifests, GitHub Actions and GitLab CI pipelines, Ansible playbooks, Docker Compose, OpenAPI specifications, static-site front matter. All of those settled on it, and the ecosystems around them are large enough that the format is not a decision anyone gets to revisit.

That shapes what a useful page about it looks like. The question is rarely whether to use YAML — it is how to avoid the specific ways it goes wrong, because it fails quietly more often than any other configuration format in common use.

There are no brackets and no closing markers. How deeply a line is indented determines what it belongs to, so a single space in the wrong place changes the meaning of the document — and frequently produces a document that is still valid, just different from what you meant.

Two rules prevent most of it. Never use tabs: the specification forbids them, and an editor that inserts one produces a parse error whose message rarely says so. And keep the indentation consistent, two spaces per level by convention, because mixing widths within a file is legal and makes the structure impossible to read at a glance.

YAML guesses what a bare value is, and the guesses have caused real outages. The famous one is the Norway problem: in YAML 1.1, an unquoted no is the boolean false, so a list of country codes turns NO into false. The same happens with on, off, y and n.

Version numbers are the second: 1.20 is the float 1.2, and the trailing zero disappears. Times are the third: 22:30 can be read as a sexagesimal number rather than a string. And a value like 0755 may be read as octal.

The defence is a habit rather than knowledge: quote anything that is meant to be text. Version numbers, country codes, identifiers, times, anything with leading zeros. YAML 1.2 fixed several of these and plenty of parsers still implement 1.1, so the habit is what protects you rather than the specification.

YAML can define a block once and reuse it. An anchor marks it, an alias refers to it, and a merge key folds a shared block into several places — which is how a CI pipeline avoids repeating the same six lines in every job.

It is genuinely useful and it is where YAML stops being readable to somebody who has not seen the syntax before. Two practical cautions: an alias is a reference rather than a copy, so what is shared is shared; and several tools that consume YAML do not implement anchors at all, or expand them in ways that surprise. Check before building a large configuration on top of them.

A block scalar written with a vertical bar keeps the line breaks: right for a script, a certificate, a message with paragraphs. Written with a greater-than sign it folds the lines into one, which is right for a long sentence wrapped for readability in the file.

Each takes a suffix controlling the final newline — a minus strips it, a plus keeps every trailing one. This matters far more than it sounds when the value is a key, a token or a script: an unexpected trailing newline is the classic reason a certificate is rejected or a command behaves differently in a pipeline than on your machine.

Three hyphens on their own line start a new document, so a single file can hold a sequence of them. Kubernetes uses this constantly — a deployment, a service and a config map in one file — and every tool that reads it expects them.

It is worth knowing because it changes what "parse this file" means. A parser that reads one document silently ignores everything after the first separator, which is how half a configuration goes missing without an error. The corresponding function is usually named for loading all documents rather than one.

Every JSON document is valid YAML, since YAML 1.2 was defined as a superset. So converting JSON to YAML is trivial and mostly cosmetic — the result is the same data, easier to read and now able to carry comments.

The other direction loses things JSON has no place for: comments, anchors, and the distinction between the several ways of writing a multi-line string. Round-tripping a Kubernetes manifest through JSON therefore strips every explanatory comment in it, which is the sort of loss nobody notices until they come back to the file in six months.

Use an editor with a YAML mode. It will show the indentation guides, convert tabs, and flag a structural error in place rather than leaving a pipeline to find it. For anything going into a repository, a linter in the commit hook is worth the ten minutes it takes to set up.

And validate before shipping when a schema exists. Kubernetes, OpenAPI and most CI systems publish one, and a validating check catches the misplaced key that a parser accepts happily and the system rejects at three in the morning.