What Is a YAML File? Syntax, Uses and How to Open One

If you work with software configuration, you have met YAML: the CI pipeline file, the container definition, the app settings. It uses the extensions .yml and .yaml, and it is plain text designed to be comfortable for people to read and write.

What YAML is

YAML stands for "YAML Ain't Markup Language", a recursive name chosen to stress that it is for data rather than document markup. The current specification is YAML 1.2. It describes the same kinds of data as JSON, namely mappings (key-value pairs), sequences (lists) and scalars (strings, numbers, booleans, null), in a layout based on indentation.

Either extension is fine. .yaml is the officially recommended extension, and .yml is common because of old three-letter extension habits. Tools usually accept both, though some look for a specific name.

The core syntax

Mappings are key: value lines:

name: docento
version: 1.6
debug: false

Sequences are lines starting with a dash:

platforms:
  - android
  - ios
  - web

Nesting uses indentation, with spaces only:

server:
  host: localhost
  ports:
    - 80
    - 443

Comments start with # and run to the end of the line:

# Used by the build pipeline
retries: 3

Strings usually need no quotes, but you can use single or double quotes when a value contains special characters or could be read as another type. Multiline text uses block scalars; see YAML multiline strings.

Multiple documents can sit in one file, separated by ---.

Rules that catch beginners

• Indentation is structure. Items at the same level must be indented by the same amount.
• Use spaces, never tabs. The YAML specification does not allow tab characters for indentation, and parsers reject them. See fixing YAML indentation errors.
• A colon needs a space after it in a mapping: key: value, not key:value.
• Unquoted values are interpreted. yes, no, on and off may become booleans in YAML 1.1 parsers, and 1.10 may become the number 1.1. See YAML gotchas.

Where YAML files are used

• CI/CD configuration, such as pipeline definitions
• Container and orchestration manifests
• Application and framework settings
• API descriptions, such as OpenAPI documents
• Static site and documentation tools, often as front matter at the top of a Markdown file
• Infrastructure automation

YAML and JSON

YAML 1.2 is designed so that most JSON is valid YAML. YAML adds comments, a less noisy syntax, multiline strings and anchors for reuse. JSON is stricter and simpler to parse. Our JSON vs YAML comparison covers when to use which.

How to open and edit a YAML file

It is plain text: use any editor. A tool that checks syntax saves time, because a single misplaced space changes the meaning or breaks the file. Docento's Text & Markdown Editor opens .yml and .yaml files locally in your browser, shows them in a fixed-width font, and reports YAML errors with the line number as you type. The Docento Android app does the same on a phone.

Best habits

• Use two-space indentation consistently.
• Quote values that might be misread, such as version numbers and country codes.
• Comment the non-obvious settings.
• Validate before committing. See YAML configuration file best practices.

Takeaway

YAML is an indentation-based text format for structured data, popular for configuration because it is readable and supports comments. Use spaces, keep indentation consistent, quote ambiguous values and validate as you edit.