What Is YAML? A Plain-English Guide to the Config Format

You cloned a project, opened it up, and there they are: a docker-compose.yml, a .github/workflows/ci.yml, maybe a folder of Kubernetes manifests — all ending in .yaml or .yml, all full of indentation and colons. If you've never been formally introduced to YAML, these files can feel like a secret handshake everyone else already knows. They're not. YAML is one of the simpler formats you'll meet, once someone explains the rules.

This guide explains what YAML is, where it's used, how its syntax works, how it compares to JSON, and how to convert between them instantly in your browser without uploading anything.

What YAML actually is

YAML stands for "YAML Ain't Markup Language" — a deliberately recursive joke that tells you something important: it's not a markup language like HTML. It's a data serialization format, a way of writing structured data (settings, lists, configuration) as plain text that both humans and programs can read.

The whole design goal is human readability. Where other formats lean on braces, brackets, and quotes, YAML leans on indentation and minimal punctuation, so a config file reads almost like an outline.

What a YAML file looks like

Here's a small example:

# Application settings
service: web
replicas: 3
debug: false
ports:
  - 80
  - 443
database:
  host: localhost
  port: 5432

A few things to notice:

• Key-value pairs use a colon and a space: service: web.
• Nesting is shown by indentation (spaces, never tabs). host and port belong to database because they're indented under it.
• Lists use a dash and a space, one item per line.
• Comments start with # — anything after it on the line is ignored.

That comment support is a big deal. It's one of the main reasons configuration files gravitate toward YAML: you can explain why a setting exists right next to it.

The core rules to keep in mind

YAML is friendly but strict about a few things:

1. Indentation is structure. Two spaces under a key means "this belongs to that key." Get the spacing wrong and the meaning changes — or the file breaks.
2. Spaces, not tabs. YAML does not allow tab characters for indentation. This is the single most common beginner mistake.
3. Types are inferred. Unquoted values get interpreted: 3 is a number, true is a boolean, null is null. Quote a value to force it to stay a string.
4. Consistency matters. Pick an indentation width (two spaces is conventional) and stick to it throughout the file.

Where YAML is used

YAML shows up almost everywhere humans hand-write configuration:

• CI/CD pipelines — GitHub Actions, GitLab CI, and CircleCI all define their workflows in YAML.
• Kubernetes — deployments, services, and config maps are written as YAML manifests.
• Docker Compose — docker-compose.yml describes multi-container setups in YAML.
• Ansible — playbooks for server automation are YAML.
• Application config — many frameworks and tools (linters, static site generators, cloud configs) accept YAML settings files.

If a tool needs a person to read and edit its configuration, there's a good chance it speaks YAML.

YAML vs JSON

YAML and JSON describe the same kinds of data — objects, lists, strings, numbers, booleans, null — so anything you can write in one, you can write in the other. The difference is in feel and purpose.

The same data in JSON:

{
  "service": "web",
  "replicas": 3,
  "ports": [80, 443]
}

And in YAML:

service: web
replicas: 3
ports:
  - 80
  - 443

Key differences:

• Syntax: JSON uses braces, brackets, and commas; YAML uses indentation and dashes.
• Comments: YAML supports them; JSON does not.
• Readability: YAML is generally easier for humans to skim, especially for deeply nested config.
• Ubiquity: JSON is the default for APIs and is parsed natively by virtually every language. YAML dominates human-edited config.

In fact, JSON is technically valid YAML in most parsers, which is why converting between them is so clean.

How to convert YAML and JSON with Toolmingo

You'll often need to move between the two — turning a JSON example from documentation into a YAML config, or converting a YAML file to JSON so your code can parse it with a built-in library. Toolmingo does this free, entirely in your browser, with no upload, so configuration that references internal hostnames or service names never leaves your machine.

1. Open the Data Converter.
2. Paste your YAML (or upload the file).
3. Choose JSON as the output — or pick YAML if you're going the other way.
4. The conversion happens instantly in the page.
5. Copy the result or download it.

The same Data Converter also handles XML, so you can move between all three formats in one place without sending data to a server.

One thing to watch when converting

Comments don't survive a trip to JSON. JSON has no comment syntax, so any # explanation lines in your YAML are dropped when you convert to JSON and won't come back if you convert again. Also double-check quoting: a value like yes or a version number like 3.10 can change meaning when YAML infers its type. If a string must stay a string, quote it. Keep your original YAML if the comments matter.

FAQ

What is a YAML file used for?

YAML files store configuration and structured data in a human-readable way. You'll find them defining CI/CD pipelines, Kubernetes manifests, Docker Compose setups, Ansible playbooks, and the settings of many development tools. Anywhere a person needs to read and edit configuration by hand, YAML is a common choice.

Why does my YAML break over indentation?

YAML uses indentation to express structure, and it only accepts spaces — never tab characters. A single misaligned space, or a tab that looks like spaces in your editor, changes what belongs to what and can break the file. Use an editor with YAML support and a consistent two-space indent.

Is it safe to convert YAML files online?

With Toolmingo, yes. The Data Converter processes everything in your browser, so your YAML is never uploaded to a server. That makes it safe for config files that reference private infrastructure, internal hostnames, or service names.