YAML Explained: What a YAML File Is and .yaml vs .yml

November 11, 2026 · 9 min read

YAML Explained: Meaning, File Uses, and .yaml vs .yml

YAML is a plain-text format for writing structured data that both people and programs can read. You'll find YAML files behind Docker, GitHub Actions and Kubernetes, and in the front matter of Markdown posts. The name stands for "YAML Ain't Markup Language," and the files end in .yaml or .yml.

What Is YAML?

The 1.2.2 specification calls it a "human-friendly, cross language, Unicode based data serialization language." In plain terms, a YAML file stores data: names and values, lists, and nested groups, laid out with indentation instead of brackets. It isn't a programming language. Nothing in the file runs; a program reads it and decides what to do.

That's the practical YAML meaning: a way to write down settings so a person can change them in any text editor. Here's a small site config:

title: My Notes
port: 8080
draft: false
tags:
  - markdown
  - docs

A parser reads this as four keys. title holds the string My Notes, port the integer 8080, draft the boolean false, and tags a list of two strings. There are no quotes, commas or braces, because indentation and the leading dashes carry the structure.

Version 1.2 set out to make the format a strict superset of JSON, so a 1.2 parser also accepts ordinary JSON. Comments, quoting and nesting rules belong in a syntax reference, so this page sticks to the concept. Our YAML format cheat sheet covers those rules, and the YAML list syntax guide covers lists in depth.

What Does YAML Stand For?

Today's expansion, "YAML Ain't Markup Language," is a recursive acronym: its first word is the name itself. Early drafts from 2001 used "Yet Another Markup Language." According to the Library of Congress format description, the designers switched to stress data over marked-up documents.

Three people designed it: Clark Evans, Oren Ben-Kiki and Ingy döt Net. The spec's history section says the 1.0 release followed three years of collaborative work on the project's mailing list.

VersionPublishedWhy it matters to you
1.0January 2004The first final spec
1.1January 2005Some widely used parsers, including PyYAML, still follow its typing rules
1.2.0July 2009Aimed at JSON compatibility and removed many implicit types
1.2.2October 2021The current revision, with no normative changes to the 1.2 language

The gap between 1.1 and 1.2 isn't academic. A parser built on the older rules can read the same file differently, which causes the gotcha at the end of this post.

What Is a YAML File Used For?

YAML files usually hold configuration: settings a person edits by hand and a program reads when it starts. You'll rarely see one used for large datasets. These are the places you're most likely to open one:

File nameToolWhat it configures
compose.yamlDocker ComposeServices, networks and volumes for a multi-container app
.github/workflows/ci.ymlGitHub ActionsWhen a workflow runs and which jobs it executes
deployment.yamlKubernetesThe desired state of an object, such as a Deployment
playbook.ymlAnsibleTarget hosts and the tasks to run on them
mkdocs.ymlMkDocsSite name, theme and navigation for a docs site
--- block in a .md fileJekyll, Hugo, DocusaurusTitle, date and other details for one page

Each of these files is written by a human and read by a program, so readability beats compactness. If you're starting a documentation site, our MkDocs Markdown guide shows how mkdocs.yml fits next to your pages.

YAML Front Matter at the Top of Markdown Files

Markdown writers often meet this format before they ever touch Docker. Static site generators read a short block at the very top of a .md file, fenced by two lines of three dashes.

---
title: Getting Started
date: 2026-11-11
draft: false
---

# Getting Started

The page body starts here.

The generator removes the block, uses its values for the page title, date and listings, and renders only the Markdown underneath. Our editor's preview doesn't render front matter, so check the final result in your site generator.

Field names and per-generator rules are in our Markdown front matter guide. To build a block without typing it by hand, the front matter generator outputs YAML, TOML or JSON with presets for Hugo, Jekyll, Astro, Docusaurus and others.

.yaml vs .yml: Which Extension Should You Use?

Both extensions mean the same thing, and a parser reads the file identically either way. The closest thing to an official answer on yaml vs yml arrived in February 2024. RFC 9512 registered the application/yaml media type, named .yaml the preferred extension, and noted that .yml is still used.

The RFC also warns against mixing them. Having both config.yaml and config.yml in the same place can cause interoperability problems. In practice, one tool may read the first while you keep editing the second.

Tool documentation beats the general rule, though. The Docker Compose docs list compose.yaml as preferred and compose.yml as accepted. Older docker-compose names still work for backwards compatibility, and when both compose.yaml and compose.yml exist, Compose picks compose.yaml. GitHub Actions accepts either extension, while MkDocs looks for mkdocs.yml by default.

We prefer .yaml for new files because it matches the RFC and reads clearly to newcomers. When a tool's docs name a .yml file, follow the docs.

Is YAML a Markup Language? YAML vs HTML and Markdown

No, and the name says so on purpose. HTML and Markdown are markup: they annotate a document so a browser or renderer can show headings, links and emphasis. This format describes data, and the program reading it decides what each value means.

A Markdown file is prose for people to read. It can carry a small data block at the top, but the two jobs stay separate. The header holds facts about the page, and the Markdown holds the page itself. Our explainer on what a Markdown file is covers the .md side. HTML is usually the end product: the page a browser displays.

JSON sits closer. A 1.2 parser reads JSON, but a JSON parser rejects the indented block style. Our YAML vs JSON comparison shows when to use each.

How to Create, Open and Check a YAML File

You don't need special software. Any plain text editor works, from Notepad and VS Code to Vim. Save the file as UTF-8 with a .yaml extension and it's ready to use.

A few habits prevent most errors:

  • Indent with spaces only. The spec forbids tab characters in indentation, and PyYAML stops with a scanner error as soon as it meets one.
  • Keep indentation consistent inside each block. Two spaces per level is a common choice.
  • Run yamllint before you commit. It's a command-line linter that checks syntax and also flags duplicate keys, long lines and trailing spaces.
  • Read the file in code through a proper parser library rather than splitting lines yourself.

If a tool rejects your file, check the line number in the error first. It usually points at a stray tab or an indentation jump.

The Norway Problem: When YAML Guesses the Wrong Type

Here's the format's real weakness: an unquoted value gets its type from how it looks. That's handy until the guess is wrong. The best-known case is the Norway problem, where the country code NO in a list of countries turns into false.

country: NO
python: 3.10

We loaded this snippet with PyYAML 6.0.3, whose PyPI description advertises a complete 1.1 parser. country came back as the boolean False, and python became the number 3.1, losing its trailing zero. Version 1.2 rules fix the first case but not the second, because 3.10 still looks like a decimal.

The cure works in every parser. Put quotes around any value that has to stay text:

country: "NO"
python: "3.10"

Both values now load as strings. A related safety rule: don't load untrusted files with a loader that can build arbitrary objects. In Python, PyYAML's docs warn that yaml.load can call any Python function, and point you to yaml.safe_load instead.

YAML comes down to one idea: data written so people can read and edit it. Use .yaml unless a tool's docs name .yml, keep tabs out of your indentation, and quote any value that must stay text. If your data block tops a Markdown post, write the body in our free Markdown editor. It runs in your browser with no account needed.