You cloned a project, opened a file called config.yml, and changed one line. Then the build failed with a message like “found character that cannot start any token.” Nothing looked wrong. The file still reads like a plain list. So what broke? Almost always, it was a single tab or one misplaced space. That tiny slip is the most common reason people go looking for what a YAML file even is.
Here is the short version. A YAML file is a plain text file that stores settings and data in a format built for humans to read. You will find it running Kubernetes, GitHub Actions, Docker Compose, and Ansible. This guide explains what YAML stands for, where a YAML file is used, how the syntax works, and how to fix the errors that send most beginners here in the first place. No prior coding needed.
A YAML file is a plain text file that stores configuration settings and structured data in a format designed to be easy for humans to read and edit. It uses indentation, key-value pairs, and dashes instead of brackets. Files end in .yaml or .yml, and tools like Kubernetes, Docker, and GitHub Actions read them.
What does YAML stand for and what does it mean?
YAML stands for “YAML Ain’t Markup Language.” That is a recursive acronym, meaning the name refers to itself. It originally stood for “Yet Another Markup Language.” The name changed to stress that YAML is built for data, not for formatting documents like HTML does, as Red Hat’s YAML overview explains. In plain terms, YAML is a way to write down structured information that both people and machines can read.
The technical label for YAML is a “data serialization language.” Serialization just means turning data into a text format that can be saved to a file or sent between programs. JSON and XML do the same job. What sets YAML apart is readability. It drops the curly braces and angle brackets those formats use and leans on simple indentation instead. That is why a YAML file often looks like a tidy outline or a shopping list rather than code.
Is YAML a programming language?
No. You cannot write logic, loops, or functions in YAML the way you can in Python or JavaScript. YAML only describes data. It holds values like text, numbers, lists, and true or false flags. A separate program reads the file and decides what to do with those values. So when a tool “runs” a YAML file, the tool is doing the work. The file is just the instruction sheet it reads.
What is a YAML file used for?
A YAML file is used mainly for configuration. It tells a program how to behave without changing the program’s own code. Because YAML is easy to read and edit, it became the default setting format across modern DevOps tools. If you work with servers, containers, or automated pipelines, you will meet YAML files daily. They store the knobs and switches those systems run on.
Here is where a YAML file is used most often, with the exact filename you will see in each case. These are the tools that make YAML worth learning, because you cannot avoid them for long once you touch cloud or automation work.
| Tool | What it does | YAML file you will see |
|---|---|---|
| Kubernetes | Runs and manages containers at scale | deployment.yaml, service.yaml |
| GitHub Actions | Automates testing and deployment | files in .github/workflows/ |
| Docker Compose | Defines multi-container apps | docker-compose.yml |
| Ansible | Automates server setup and config | playbook.yml |
| GitLab CI | Runs build and test pipelines | .gitlab-ci.yml |
YAML beyond DevOps: frontmatter and app settings
YAML is not just for engineers. Static site builders like Jekyll and Hugo use a small YAML block at the top of each page called frontmatter. It sets the title, date, and tags for a blog post. Many apps also store their preferences in a settings file written in YAML. So a marketer editing a Hugo blog or a writer tweaking site config is using YAML too, often without knowing the name. The same simple rules apply everywhere.
How to read YAML syntax
YAML syntax rests on three building blocks: key-value pairs, lists, and indentation. A key-value pair is written as key: value with a space after the colon. A list uses a dash and a space before each item. Indentation with spaces shows what belongs to what. Master these three and you can read most YAML files you meet.
Look at this example. It describes a person, their skills, and their address. Notice how the indentation groups related lines, exactly like an outline. The skills key holds a list, so each skill starts with a dash. The address key holds more key-value pairs nested underneath it.
name: Jordan Lee
role: Developer
active: true
skills:
- Python
- Docker
- YAML
address:
city: Austin
state: TX
zip: "73301"A few things to spot. The value true is read as a boolean, a yes or no flag, not the word “true.” The zip code sits in quotes so YAML keeps it as text instead of stripping the leading structure a number might imply. Comments start with a # and are ignored by the parser. That is most of what you need to read a real file.
What the colon, dash, and three dashes mean
People search for what specific symbols mean in YAML, so here is the quick key. The colon separates a key from its value. The dash marks a list item. Three dashes (---) mark the start of a new document, letting one file hold several separate YAML documents. Three dots (...) mark the end of a document without starting another. You will see --- often at the top of Kubernetes files.
The tabs versus spaces rule that breaks your file
The single most common YAML error is using a tab for indentation. The YAML 1.2.2 specification forbids tab characters for indentation, so you must use spaces. A tab where a space is expected causes an immediate parse failure. Worse, tabs and spaces look identical on screen, so the mistake stays invisible until the parser rejects the file.
This is why so many people arrive at a “what is a YAML file” search already frustrated. Their editor inserted a tab when they pressed the Tab key, and the build hung with a cryptic message. The fix is to make whitespace visible and convert tabs to spaces. Most editors do both in seconds once you know the setting.
A tab where a space is expected is an immediate error. This is the number-one cause of “my YAML won’t parse,” and it’s invisible in most editors.
YAML indentation guides, 2026
Three rules keep you safe. Use spaces only, never tabs. Use two spaces per level, which is the near-universal convention even though the spec only requires consistency. Keep every item at the same level lined up in the same column. In VS Code, turn on “Render Whitespace” and run “Convert Indentation to Spaces” to clean a file fast.
Why does YAML forbid tabs at all?
Tabs render at different widths in different editors. A tab might look like two spaces on your screen and eight on someone else’s. Since YAML uses indentation to define structure, an ambiguous tab width could change what the data means. Banning tabs removes that ambiguity. It is a strict rule, and many developers find it annoying, but it keeps files consistent across every machine that reads them.
YAML vs JSON vs XML: how they compare
YAML, JSON, and XML all store structured data, but they read very differently. YAML uses indentation and looks the cleanest. JSON uses curly braces and is the standard for web APIs. XML uses angle-bracket tags and is the oldest and most verbose. The same data written in each shows the gap at a glance.
| Feature | YAML | JSON | XML |
|---|---|---|---|
| Structure marker | Indentation | Curly braces | Tags |
| Comments | Yes (#) | No | Yes |
| Readability | Highest | Medium | Lowest |
| Best for | Config files | Web APIs | Documents, legacy systems |
| File extension | .yaml, .yml | .json | .xml |
Is YAML really a superset of JSON? A closer look
You will read almost everywhere that “YAML is a superset of JSON,” meaning every JSON file is also valid YAML. That claim needs a caveat most guides skip. It is only fully true for YAML version 1.2, and only when a parser runs in 1.2 mode. The official YAML spec (revision 1.2.1) states YAML can be viewed as a natural superset of JSON, and that this was the point of the 1.2 revision.
Here is the catch. Many real parsers still default to the older YAML 1.1 behavior for backward compatibility. Under 1.1, a value like 1e2 can parse as the text “1e2” instead of the number 100, and the word no can become the boolean false. So a JSON file can technically parse differently, or wrongly, in a parser that has not switched to 1.2. The clean takeaway: treat the superset claim as true for modern 1.2 parsers, and verify if you rely on it in production. Competitors state the claim flatly. The primary source and real parser tests are more careful.
Common YAML errors and how to fix them
Most YAML errors come from three sources: tabs, inconsistent indentation, and a missing space after a colon. The parser messages sound cryptic, but each maps to a simple cause. This table pairs the exact error text you are likely to see with what actually went wrong and how to fix it fast.
| Error message | Likely cause | Fix |
|---|---|---|
| found character that cannot start any token | A tab used for indentation | Replace all tabs with spaces |
| mapping values are not allowed here | Missing space after a colon, or wrong indent | Add a space after the colon, then realign the line |
| could not find expected block entry | List items indented inconsistently | Line up every dash in the same column |
| bad indentation of a mapping entry | Mixing 2-space and 4-space indents in one block | Use one consistent indent width |
One habit prevents most of these: run your file through a YAML validator before you save or commit it. Paste the file, and the validator flags the exact line and column of any problem. If the error points to line 12, also check lines 9 through 11, because indentation problems often start a few lines above where the parser gives up.
A quick pre-commit checklist
- No tabs anywhere. Turn on “show whitespace” to confirm.
- Every colon in a key-value pair has a space after it.
- All items at the same level share the same indentation.
- Values that look like numbers or booleans but should stay text are quoted.
- The file passes a YAML validator with zero errors.
Frequently asked questions
What is the difference between .yaml and .yml?
There is no difference in how they work. Both extensions hold identical YAML content and parse the same way. The official recommendation from yaml.org is .yaml. The shorter .yml survives from old systems that limited file extensions to three letters. Some tools expect one or the other by name, so match whatever a project already uses. When you create a fresh file with a free choice, .yaml is the safer default.
How do I open a YAML file?
Any text editor opens a YAML file, since it is plain text. Notepad on Windows or TextEdit on Mac will show it. For editing, use a code editor like VS Code with a YAML extension. That adds color highlighting and error checking, which makes the structure far easier to see. Avoid word processors like Microsoft Word. They can add hidden formatting that corrupts the file and breaks parsing.
Can YAML use tabs for indentation?
No. The YAML specification forbids tab characters for indentation. You must use spaces. This is the single most common cause of YAML files that will not parse, because a tab looks identical to spaces on screen. Set your editor to insert spaces when you press the Tab key for .yaml and .yml files. Two spaces per indentation level is the standard convention that nearly every tool expects.
What does YAML stand for?
YAML stands for “YAML Ain’t Markup Language,” a recursive acronym that points back at itself. It first stood for “Yet Another Markup Language.” The creators changed the meaning to make clear that YAML handles data, not document formatting the way HTML or XML markup does. The name is a small joke, but the point is real: YAML describes structured information, not the look of a page.
Is a .yaml file safe to edit by hand?
Yes, editing by hand is normal and expected, since YAML was designed for exactly that. The risk is not the editing but the whitespace. Change values freely, but keep indentation consistent and never introduce a tab. Save a backup copy before large edits to config that runs in production. After editing, run the file through a validator so a stray space does not reach your build or deployment.
What is a YAML file used for in simple terms?
A YAML file is used to store settings that tell software how to run. Think of it as a labeled instruction sheet a program reads at startup. It sets things like which containers to launch, which tests to run, or what title a web page shows. It keeps those choices separate from the program’s code, so you can change behavior by editing text rather than rewriting the software.
Why do Kubernetes files start with three dashes?
The three dashes (---) mark the start of a YAML document. One file can hold several documents separated by these markers, which is common in Kubernetes when you define a deployment and a service together. The dashes tell the parser where one document ends and the next begins. If you only have a single document, the three dashes are optional, though many teams add them for clarity.
Does the YAML format change often?
No, and that is good news for anyone learning it. According to the official YAML website, the current specification is version 1.2, revision 1.2.2, published October 1, 2021. There has been no newer version since. The 1.2.2 update fixed wording and errata but made no changes to the language itself. So what you learn about YAML syntax today will stay accurate. The stability is one reason it spread so widely.
Wrapping up
Back to that broken build. The file that would not parse almost certainly had a tab hiding where a space belonged, or two lines that did not line up. Now you know why. A YAML file is just plain text that stores settings in a readable, indentation-based format. Its rules are few: spaces not tabs, a space after each colon, and consistent alignment down the file.
Once those rules click, YAML stops being a source of mystery errors and becomes the quiet, readable format it was meant to be. You can open a Kubernetes manifest or a GitHub Actions workflow and follow the structure like an outline. Keep a validator handy for the tricky files, and watch your whitespace on the rest. So the next time you open a .yaml file in a new project, what is the first thing you will check?
