YAML for Beginners: A Quick Start Guide

If you work with Docker, Kubernetes, GitHub Actions, or almost any modern DevOps tool, you have seen YAML files. They are everywhere in configuration. But if you are coming from a background where you mostly worked with JSON or INI files, YAML's whitespace-based syntax can feel confusing at first.

This guide will get you comfortable with the basics in about five minutes.

What is YAML?

YAML stands for "YAML Ain't Markup Language." It is a data serialization format designed to be human-readable. Unlike JSON, which uses braces and brackets, YAML uses indentation to represent structure. Unlike XML, there are no tags. The result is a format that is clean, minimal, and easy to read at a glance.

YAML files typically use the .yml or .yaml extension. Both are equivalent and accepted by all tools that read YAML.

Basic syntax rules

YAML has just a few rules to learn:

• Key-value pairs are written as key: value. The colon must be followed by a space.
• Indentation defines nesting. Use spaces, never tabs. Two spaces per level is the convention.
• Lists use a dash followed by a space: - item. Each item starts on its own line at the same indentation level.
• Strings usually do not need quotes unless they contain special characters like colons, hashes, or leading spaces.
• Comments start with a hash symbol. Everything after the hash on that line is ignored.
• Booleans are written as true or false (lowercase).
• Null values are written as null or simply left empty after the colon.

Where YAML is used

YAML has become the standard configuration format for a wide range of tools:

• Docker Compose - the docker-compose.yml file defines services, networks, and volumes for multi-container applications.
• Kubernetes - every Kubernetes resource (pods, deployments, services) is defined in YAML manifests.
• CI/CD pipelines - GitHub Actions, GitLab CI, CircleCI, and most other CI tools use YAML for pipeline configuration.
• Ansible - playbooks and inventory files are written in YAML.
• Static site generators - tools like Jekyll, Hugo, and Astro use YAML for front matter and configuration.

The reason YAML won out over JSON for configuration is readability. Configuration files are read and edited by humans far more often than they are read by machines. YAML's clean syntax makes it easier to scan, edit, and review in pull requests.

Common mistakes to avoid

Most YAML errors come from a few common sources:

• Mixing tabs and spaces - YAML strictly requires spaces for indentation. A single tab character will cause a parse error. Configure your editor to insert spaces when you press the Tab key.
• Inconsistent indentation - if you use 2 spaces for the first level, use 2 spaces for every level. Mixing 2 and 4 spaces within the same file causes confusing errors.
• Forgetting the space after the colon - key:value is not valid YAML. It must be key: value with a space.
• Unquoted special strings - values like yes, no, on, and off are interpreted as booleans in some YAML parsers. If you mean the literal string "yes", wrap it in quotes.

Converting between JSON and YAML

JSON and YAML are interchangeable for data representation. Any valid JSON can be converted to YAML and vice versa. This is useful when you have data in one format and need it in the other - for example, copying an API response (JSON) into a Kubernetes config file (YAML).

PrivConvert's JSON to YAML converter handles this conversion instantly in your browser. Paste in your JSON, get clean YAML output with proper indentation. You can also go the other direction if you need to convert YAML back to JSON for an API or script.

If you are also working with CSV data, check out our guide on CSV vs JSON vs XML for a broader comparison. And for validating your YAML files, the converter tool will flag syntax errors during conversion, which makes it a handy validator too.