What is a YAML File?Data

📖 What is a YAML File?

A YAML file is a plain-text file that holds structured information in a layout people can read at a glance. It is used mostly to store settings and configuration, and its whole design goal is to be easy on the eye, so in place of the braces and quotation marks common to other data formats, it relies on plain indentation to signal how the pieces fit together.

The name is a small joke that developers enjoy. The letters expand to "YAML Ain't Markup Language", a tongue-in-cheek label announcing that its job is carrying data, not marking up documents the way HTML does. Open one in any text editor and you will usually understand the gist straight away, because a YAML file reads almost like a tidy list of labels and values, with indentation doing the work of showing what belongs inside what.

You will meet YAML files most often as the settings behind software and automated tasks. Tools that build, test and deploy code lean on them heavily, and if you have configured almost anything modern in development you have probably edited a .yaml file, perhaps without thinking much about the format itself. What makes it worth understanding is that a small slip in spacing can change the meaning, so a little knowledge of how YAML is laid out goes a long way toward editing one confidently.

⚡ Quick Facts

🔤 .yaml vs .yml

The first thing that puzzles people about YAML is why the same format turns up with two different extensions, .yaml and .yml. The short answer is reassuring. They are exactly the same thing, and every program that reads YAML happily accepts either one.

The two spellings are a leftover from computing history. When YAML appeared in the early 2000s, many systems still limited file extensions to three letters, a holdover from older Windows and DOS days, so the trimmed .yml caught on out of necessity. Once that limit fell away, the fuller .yaml became the tidier choice, and the official YAML site has recommended .yaml as the preferred spelling since 2006. Today the pick is mostly a matter of habit and community. Some ecosystems lean toward .yml, notably Ruby on Rails and Docker Compose, while others favour .yaml, such as Kubernetes and many newer tools. Neither is more correct in any way that affects how the file works.

For a new file the sensible default is .yaml, since it matches the official recommendation and spells out the format clearly. The one piece of advice worth heeding is to avoid renaming a pile of existing .yml files just to be consistent, because automated build scripts often refer to files by their exact name, and a mass rename can quietly break them. In practice the wise rule is simple. Follow whatever the surrounding project already uses, and reach for .yaml when you are starting fresh.

✏️ YAML Syntax Basics

Most of YAML comes down to three simple ideas, and once they click a YAML file stops looking like code and starts looking like a neatly organised note.

The first idea is the pair. You write a label, a colon, a space, then a value, so name: Ada reads exactly as it looks. The second idea is the list, where each item sits on its own line behind a dash and a space, giving a clean column of entries. The third idea is nesting, and this is where indentation earns its keep. By pushing lines further to the right with spaces, you show that they belong inside the line above, building a tree of information without a single bracket. Importantly the spacing must be spaces, never tabs, because YAML forbids tab characters for indentation, and two spaces per level is the common habit. Values themselves can be text, numbers, true or false, or left empty, and YAML is usually clever enough to tell which is which.

# a mapping of key and value pairs
name: Ada Lovelace
active: true
age: 36

# a nested block, shown by indentation
address:
  city: London
  country: England

# a list, one item per dash
skills:
  - mathematics
  - writing
  - computing

Read that top to bottom and it barely needs explaining, which is the entire point of YAML. The labels sit on the left, their values on the right, and the indentation quietly shows that the city and country belong to the address while the three skills form a list of their own.

📝 Multi-Line Text and Comments

Two everyday touches make YAML pleasant to work with, and both turn up constantly once you start reading real files.

The first is the comment. Anything after a hash symbol on a line is ignored by the software, so you can leave notes for yourself and others right beside the settings they explain, which is a big part of why YAML files feel so approachable. The second is a tidy way to hold blocks of text that run over several lines. A vertical bar tells YAML to keep the text exactly as written, line breaks and all, which suits things like a message or a script, while a greater-than sign folds the lines together into one flowing paragraph, handy for a long sentence you would rather wrap neatly in the file. Both let you store sizeable chunks of text without wrestling with quotes or escape characters.

# the bar keeps every line break
message: |
  Dear reader,
  Thank you for your note.

# the arrow folds lines into one
summary: >
  This long sentence will be
  joined into a single line
  when the file is read.

🔗 Anchors and Reuse

One feature sets YAML apart from simpler formats and often surprises newcomers, the ability to write something once and reuse it elsewhere in the same file.

YAML lets you tag a value or a block with an anchor, marked by an ampersand, and then point back to it later with an alias, marked by an asterisk. Wherever the alias appears, YAML behaves as though you had copied the anchored content into that spot. The benefit is that a setting shared across several places lives in exactly one location, so changing it once updates every use, and the file stays shorter and less error-prone. You tend to see this in larger configuration files where the same block of options would otherwise be repeated many times. It is not something every YAML file needs, but when you spot an ampersand and an asterisk, this reuse is what they mean.

# the & anchor names a block
defaults: &defaults
  timeout: 30
  retries: 3

server_a:
  <<: *defaults
  host: alpha.example.com

server_b:
  <<: *defaults
  host: beta.example.com

Here both servers pull in the same defaults without repeating them, so a single edit to the timeout would apply to each one.

📑 Many Documents in One File

A single .yaml file can hold more than one separate document, which is a neat trick worth recognising when you meet it.

Three dashes on their own line act as a divider, marking the start of a new document within the same file, and an optional three dots can signal the end of one. Everything between the markers is treated as an independent piece, so a program reading the file works through each document in turn. This is genuinely useful when several related but distinct sets of settings naturally belong together, letting one file carry them all while keeping each cleanly separated. If you open a YAML file and notice lines of three dashes scattered through it, you are looking at several documents stored side by side rather than one long one.

name: first document
role: web server
---
name: second document
role: database

⚠️ Common YAML Mistakes

Because YAML puts so much meaning into spacing and plain words, a handful of small mistakes catch almost everyone at some point, and knowing them in advance saves a lot of head-scratching.

The most frequent trip-up is using a tab to indent instead of spaces. On screen a tab can look just like spaces, yet the format refuses it outright, so a single stray tab triggers a baffling error, and the cure is to have your editor type spaces instead. Inconsistent indentation is close behind, since lines that should line up but do not will change the structure in ways you did not intend. Another classic surprise is that certain plain words are read as true or false, so an unquoted value like no or off can quietly become a boolean rather than the text you meant, which famously bites people whose data includes the country code for Norway. The safe habit is to wrap any such value in quotes so it stays as text. Forgetting the space after a colon is another small one, since name:Ada is not the same as name: Ada to a parser. None of these are hard to avoid once you know them, and a quick pass through a YAML validator will catch them before they cause trouble.

🔢 YAML Data Types

One of the conveniences of YAML is that it works out what kind of value you have written, so a bare number is read as a number and the word true is read as a yes-or-no value without you saying so. This cleverness is handy most of the time, but it is also the source of the surprises worth knowing about.

The everyday types are text, whole numbers, decimals, true-or-false values and empty values. You write them plainly and YAML reads them the obvious way, so quantity followed by 42 becomes a number while a name followed by a word stays as text. An empty value can be written as null, as a tilde, or simply left blank, all meaning the same nothing. Dates are recognised too, so a value that looks like a calendar date is treated as one. The catch is that this guessing can misfire, and the fix is always the same, wrap the value in quotes to force it to stay as text. That is how you keep a version number like 1.0 or a postcode with a leading zero from being turned into something you did not intend.

title: Ada Lovelace      # text
count: 42               # number
active: true            # true or false
nickname: null          # empty, same as ~ or blank

# quote when a value should stay text
version: "1.0"          # not the number 1
zip: "07030"            # keeps the leading zero

💬 Single vs Double Quotes

When you do need quotes, YAML gives you two kinds and they behave a little differently, which trips people up until they see the rule.

Single quotes keep the text exactly as typed, treating everything inside as literal characters, which makes them ideal for things like file paths or text that itself contains backslashes. Double quotes are cleverer, letting you use escape codes such as a backslash-n for a new line or a backslash-t for a tab, so you reach for them when you actually want those special effects. As a rule of thumb, prefer single quotes for plain literal text and switch to double quotes only when you need an escape sequence. You genuinely need quotes of some kind whenever a value would otherwise be misread, so quote anything that looks like a number but should stay text, anything that reads as true, false or null when you mean the word, and any value carrying a colon followed by a space, since that pattern would otherwise look like a new key.

📂 How to Open a YAML File

Opening a YAML file could hardly be simpler, because it is ordinary text underneath, so anything that can show text can show a YAML file.

On any computer you can open one in the built-in editor, whether that is Notepad on Windows or TextEdit on a Mac, and see its contents straight away. For anything beyond a quick peek, a proper code editor is far nicer, and the free VS Code is a popular pick because, with a YAML add-on, it colours the different parts, lines up the indentation and flags mistakes as you type, which is a real help given how much spacing matters. If you only want to inspect a file without installing anything, a web-based viewer such as the one from Univik displays a YAML file neatly in the browser. Whichever you choose, remember that the indentation is meaningful, so it pays to use an editor that shows spaces clearly rather than one that might silently swap in tabs.

🔄 How to Convert a YAML File

YAML and JSON are close cousins that hold the same kinds of information in different clothing, so converting between them is a common and painless task.

The two formats map onto each other almost perfectly, which is why so many tools accept both. You might turn YAML into JSON when a program or an interface expects JSON, or turn JSON into YAML to make a dense file friendlier to read and edit. Most programming languages can do the swap in a couple of lines, and for a one-off job an online converter like the one Univik provides changes YAML to JSON and back in the browser without any setup. The result carries the same data, just arranged in the other style, so nothing meaningful is lost in the trip. It is worth a quick check afterwards that the converted file still reads the way you expect, since the two formats handle a few edge cases slightly differently, but for everyday data the round trip is smooth.

🔒 Is YAML Safe?

A YAML file is just text and holds no program of its own, so reading one to a person is perfectly safe. The care needed is on the software side, when a program loads a YAML file automatically, and it is worth understanding because it is a genuine security point rather than a scare.

YAML has an advanced feature that lets a file ask for special object types, and in several languages a carelessly loaded file can turn that feature into running unwanted code on the machine doing the loading. The danger only appears when a program uses the fully powered loading function on a file from a source it does not trust. The safe habit, followed as standard by careful developers, is to use the restricted loading option instead, which sticks to the plain types like text, numbers and lists and ignores the risky part entirely. In Python this is the well-known difference between the plain load call and the safe one, and other languages have their own equivalent. For anyone simply opening and reading a YAML file there is nothing to worry about, and for anyone loading one in code the rule is short, treat files from unknown sources with caution and always use the safe loader.

❓ Frequently Asked Questions

📝 Summary