What is a YAML file? Syntax, examples, and common mistakes

 A YAML file is a plain text file that stores settings and other structured information in a format both people and programs can read. It uses indentation and simple punctuation, like colons and dashes, to show how pieces of information relate to each other.

You will usually meet YAML when a tool asks you to configure it: a deployment pipeline, a container setup, or a hosting platform. This guide explains how YAML is put together, walks through real examples, and covers the handful of mistakes behind most broken YAML files.

What is YAML used for?

Key takeaway: YAML is one of the most common formats for configuration files in development tools, because people can read and edit it without special software.

The name is a recursive joke: YAML stands for "YAML Ain't Markup Language". The point is that YAML describes data, such as settings, lists, and options, rather than formatting a document the way HTML does.

You will find YAML files in many of the tools developers use every day:

Configuration files are read and changed by people far more often than they are written from scratch, which is where a readable format pays off. YAML files often sit alongside other configuration files in a project, such as a .env file that holds secrets. Our guide What is .env? covers that one.

YAML syntax basics, with an example

Key takeaway: almost every YAML file is built from key and value pairs, indentation for nesting, and dashes for lists.

Here is a short YAML file for a made-up web app. Every part of it is explained below.

# Settings for a small web app
app_name: recipe-finder
port: 8080
debug: false

database:
  host: localhost
  name: recipes

features:
  - search
  - favorites
  - shopping-list

welcome_message: |
  Welcome to Recipe Finder.
  Search by ingredient to get started.

Text usually needs no quotes, but you can add single or double quotes around any value. Quotes are how you tell YAML to treat something as text when it looks like a number or a switch (see the mistakes section below).

Indentation carries the structure. A line indented under a key belongs to that key, and lines at the same indentation are siblings. The exact number of spaces is up to you, as long as each level is consistent. Two spaces per level is a common choice.

YAML vs JSON

Key takeaway: YAML and JSON can hold the same information. YAML is easier for people to read and edit, and JSON is stricter and more common for data sent between programs.

JSON is another text format for structured data, used heavily by websites and APIs. Here is the same app configuration from above, written as JSON:

{
  "app_name": "recipe-finder",
  "port": 8080,
  "debug": false,
  "database": {
    "host": "localhost",
    "name": "recipes"
  },
  "features": ["search", "favorites", "shopping-list"],
  "welcome_message": "Welcome to Recipe Finder.\nSearch by ingredient to get started.\n"
}

The two are closely related. YAML 1.2, the current version of the YAML specification, was designed so that JSON is valid YAML. That is why some tools accept either format for the same file.

Why your YAML breaks: common mistakes and how to fix them

Key takeaway: most YAML problems are indentation or spacing mistakes, and the worst ones raise no error at all. The file loads, but it means something different from what you wrote.

YAML errors come in two kinds. Some stop the file from loading and show an error message, which is annoying but easy to spot. Others load without complaint and quietly change your settings, so the app runs with values you never meant to set. Where it helps, each mistake below shows the broken version first, then the fix.

1. Using tabs instead of spaces

YAML does not allow tab characters for indentation. A single tab, often added by an editor without you noticing, makes the whole file fail to load.

Fix: set your editor to insert spaces when you press Tab. Most code editors have this setting, and many apply it to YAML files automatically.

2. Indenting a line to the wrong level

If a line ends up one level too far left, it stops belonging to the group above it. YAML reads it as a separate setting, with no error.

# Broken: name is no longer part of database
database:
  host: localhost
name: recipes

# Fixed
database:
  host: localhost
  name: recipes

A line indented by one space too many usually does produce an error, often worded as "mapping values are not allowed here". If you see that message, check the indentation of the line it points to and the line above it.

3. Forgetting the space after a colon or dash

YAML needs a space after the colon in key: value and after the dash in a list item. Without it, YAML sees ordinary text.

# Broken: read as one line of text, not a list
features:
  -search
  -favorites

# Fixed
features:
  - search
  - favorites

4. Using a colon inside a value

A colon followed by a space inside a value confuses YAML, because it looks like the start of a new setting.

# Broken: fails to load
message: Note: restart the app after changes

# Fixed
message: "Note: restart the app after changes"

5. Values YAML reads as something else

YAML guesses what kind of value you mean, and sometimes it guesses wrong. These are the classic surprises:

Fix: put quotes around any value that must stay as text, such as version: "1.10" or country: "NO". Leave quotes off values a tool expects as real numbers or true and false switches, such as a port number.

6. Repeating a key

If the same key appears twice at the same level, many tools keep the last value and ignore the first without telling you. Stricter tools stop with an error instead.

port: 8080
# ...many lines later
port: 9090

The app runs on port 9090, and the first line is silently ignored. In a long file, search for the key before adding it.

How to check a YAML file before you use it

Key takeaway: let a tool check your YAML. An editor extension catches mistakes as you type, and a validator confirms the whole file before you rely on it.

There are three common ways to check a YAML file, from lightest to most thorough:

1. Use an editor that understands YAML. Code editors such as Visual Studio Code have YAML extensions that underline errors as you type. Some also know the expected layout of specific files and suggest valid settings as you write.
2. Run a linter. A linter is a small program that reads a file and reports problems. yamllint is a free, open source option for YAML, and it flags style issues like inconsistent indentation as well as outright errors.
3. Use the checker that comes with your tool. Many tools can check their own configuration files, which catches mistakes a general YAML checker cannot, such as a setting with the wrong name.

Online YAML validators work too, but be careful with what you paste into them. Configuration files sometimes contain passwords or internal addresses, and those should not go into a website you do not control.

If an AI assistant wrote the file, check it the same way. AI-generated YAML often has valid syntax, so it loads without errors. The mistakes tend to be in the content instead: a setting name the tool doesn't recognize, an option from an older version of the tool, or a value at the wrong level. A tool's own checker, option 3 above, is the one most likely to catch them.

YAML on Upsun Cloud: reading a real configuration file

Key takeaway: Upsun Cloud describes an entire project in one YAML file, .upsun/config.yaml, and its command line tool can check that file before you deploy.

On Upsun Cloud, the apps you run, the services they use (such as a database), and the web addresses that reach them all live in one YAML file. It sits in a folder called .upsun at the top of your project. Running upsun project:init creates a starting version based on the code it finds.

Here is a small example: a Node.js app connected to a PostgreSQL database.

applications:
  myapp:
    type: "nodejs:26"
    relationships:
      database:
    web:
      commands:
        start: "node index.js"

services:
  database:
    type: "postgresql:17"

routes:
  "https://{default}/":
    type: upstream
    upstream: "myapp:http"

Here is what each part does:

• The file has three top-level keys, applications, services, and routes, which is the structure Upsun Cloud expects.
• Under applications, one app called myapp runs on Node.js 26 and starts with the command node index.js.
• Under services, a PostgreSQL 17 database is named database.
• The relationships entry connects the app to that database. The name database has to match in both places. If one is misspelled, the app cannot find its database.
• Under routes, web traffic to the project's address goes to myapp.

The common mistakes above apply here too. A misplaced indent can move relationships out from under myapp. The quotes in this example are optional, but quoting values that contain colons or curly braces is a safe habit.

To check the file before you push it, run upsun app:config-validate in your project folder. It validates your project's configuration files, so mistakes surface on your machine before a deployment does. If a coding agent edits this file for you, tell it to run the same command after every change. Our guide What is an AGENTS.md file? shows how to write that instruction down once so every agent follows it. You can also connect your editor to Upsun Cloud's published schema, so it suggests valid settings and flags mistakes as you type. The Upsun Developer Center explains how to set that up.

For everything the file can contain, see YAML on Upsun Cloud in the Upsun docs.

On Upsun Cloud, this one file describes your whole project, and every environment is built from it. You can deploy on Upsun Cloud free for 15 days, with no card needed, or see how Git-driven automation turns configuration changes into deployments.

Frequently asked questions (FAQ)

What does YAML stand for?

YAML stands for "YAML Ain't Markup Language". The name makes the point that YAML is for describing data, such as settings and lists, rather than formatting documents.

What is the difference between .yaml and .yml?

Nothing. Both extensions mean the same format. Some tools expect one or the other, so use whichever the tool's documentation shows.

Can YAML use tabs?

No. YAML only allows spaces for indentation. Set your editor to insert spaces when you press Tab.

How many spaces should I indent YAML with?

Any number works as long as each level is consistent. Two spaces per level is a common choice.

Why does my YAML say "mapping values are not allowed here"?

This error usually means a line is indented differently from its neighbors, or a value contains a colon followed by a space. Check the indentation of the line the error points to, and put quotes around any value that contains a colon.

Is YAML better than JSON?

Neither is better in general. YAML is easier for people to read and edit, which suits configuration files. JSON is stricter and simpler for programs to produce, which suits data sent between systems.

How do I open a YAML file?

Any text editor can open it, because a YAML file is plain text. A code editor with a YAML extension makes it easier to read and to spot mistakes.