YAML FAQ¶
YAML is designed to be human-friendly. Humans, however, have questions.
Here are short answers to some of the ones that come up most often.
What does YAML stand for?
YAML Ain't Markup Language.
It is a recursive acronym meant to emphasize that YAML represents data, rather than marking up a document. Early on, the name meant “Yet Another Markup Language.” The letters stayed; the meaning grew up.
How do you pronounce YAML?
It rhymes with camel.
Who created YAML?
YAML was created by Clark Evans, Ingy döt Net and Oren Ben-Kiki. The language emerged from their work in 2001 and a much wider community has helped shape and implement it ever since.
For the longer and considerably more colorful version, read In The Beginning.
Should I use .yaml or .yml?
Prefer .yaml when you get to choose. .yml means the same thing and
remains common, especially where older systems once limited extensions to
three characters.
How many spaces should indentation use?
YAML does not require a particular number. Two spaces is a popular convention; consistency is what matters.
Tabs must not be used for indentation. They can still appear inside quoted scalar values, where they are data rather than structure.
When should I quote a string?
Plain, unquoted strings are one of YAML's nicest features. Quote a value when punctuation makes it ambiguous, when leading or trailing whitespace matters, or when another system might mistake it for a boolean, number, date or null value.
definitely-a-string: "2026-08-11"
also-a-string: "true"
contains-a-comment-mark: "hello # still part of the value"
Quoting values such as yes, no, on and off is especially wise when
your document may pass through older YAML 1.1 tooling.
Is JSON valid YAML?
JSON syntax is valid YAML 1.2 syntax, so a YAML parser can read JSON. YAML also adds comments, block formatting, anchors, aliases, tags and other features intended for human-authored data.
Real-world tools do not all implement the same YAML version or schema, so test the exact parser used by your application when interoperability matters.
What are anchors and aliases?
An anchor names a node and an alias refers to that same node elsewhere in the document.
Here, *message refers to the scalar marked with &message. Anchors and
aliases can make repeated structures easier to maintain, but a little goes
a long way.
Can a mapping contain the same key twice?
Don't do it. YAML mapping keys are required to be unique, but parsers vary in how they handle duplicates: some report an error, while others silently keep one value. A duplicate key can therefore turn a typo into a very confusing bug.
Why does valid-looking YAML fail to parse?
Start by checking:
- indentation that does not line up with its siblings;
- a tab hiding among spaces;
- a missing space after
:; - a
:or#that belongs inside a quoted string; and - an unclosed quote, bracket or brace earlier in the document.
The reported line is often where the parser finally became certain there was a problem, not necessarily where the problem began.
Is it safe to load YAML from strangers?
Treat YAML like any other structured input: use your library's safe-loading mode, limit resource consumption and validate the resulting data before using it.
Some libraries can construct application-specific objects from tagged values. That can be powerful for trusted files and dangerous for untrusted ones. Do not enable those features unless you intend to use them.
Which YAML version should I use?
New work should generally target the YAML 1.2 family. Be aware that some widely used libraries still expose YAML 1.1 behavior by default, especially around implicit scalar types.
The official specification and related resources live at yaml.org.
Where can I ask another question?
The YAML community gathers in the YAML Matrix chat. Questions also make excellent ideas for future posts.