YAML's flexibility makes it easy to write a configuration file that works today and confuses everyone, including you, in six months. These practices keep files readable, predictable and safe.
Formatting
Use two spaces for indentation, and never tabs. Tabs are not allowed for YAML indentation. Configure your editor to insert spaces and to show whitespace characters.
Be consistent about list style. Either indent list items under their key or keep them flush with it, but pick one for a file. Mixed styles are legal but make errors easy to introduce.
Keep lines short enough to read. Use folded block scalars (>) for long text. See YAML multiline strings.
Use a formatter or linter so style is enforced mechanically, not by review comments.
Quote anything ambiguous
Unquoted values are guessed. Quote:
- version numbers, such as
"3.10" - codes and identifiers, such as country codes or zip codes
- times and dates you want as text
- anything with a colon, hash or leading special character
This habit prevents the problems described in YAML gotchas.
Comment generously
YAML supports comments with #, which is one of its main advantages over JSON. Explain why a setting has its value, not just what it is, and note units and acceptable ranges:
# Seconds. The upstream API rate-limits at 60 requests a minute.
request_timeout: 30
Structure
- Keep nesting shallow. Deep trees are hard to scan. Three or four levels is usually enough.
- Group related settings under a common key.
- Use clear, consistent key names, in one style such as
snake_caseorkebab-case, as the consuming tool requires. - Avoid duplicated blocks. Use anchors and aliases for shared settings:
defaults: &defaults
retries: 3
timeout: 30
production:
<<: *defaults
timeout: 60
Anchors (&name) mark a node, aliases (*name) reuse it, and the merge key (<<) combines mappings. Merge keys are a widely supported extension rather than part of the core YAML 1.2 specification, and not every tool honours them. Use them where your tool documents support. Heavy use of anchors can make a file harder to read, so keep it modest.
Secrets
Do not put passwords, API keys or tokens in a YAML file that goes into version control. Reference them from environment variables or a secrets manager. If a file does contain secrets, keep it out of the repository; see keeping .env files out of git for the same principle with another format.
Safe loading
If you write code that reads YAML, use the library's safe loading mode. Some YAML libraries can construct arbitrary objects from tags in the document, and loading untrusted YAML with an unsafe loader has been the source of serious vulnerabilities. Safe loaders restrict the output to plain data types.
Validate
- Syntax check on every edit, which catches indentation and quoting errors. Docento's Text & Markdown Editor does this for
.ymland.yamlfiles in the browser and on Android. - Schema validation in your build, for example with JSON Schema applied to the parsed data, to catch wrong keys and wrong types, which a syntax check cannot.
- Run the tool that consumes the file, with a dry-run option if it has one.
Version control habits
- Keep configuration files in version control, and review changes to them like code.
- Make small, focused changes so a diff shows intent.
- Add a short header comment saying what the file configures and who consumes it.
Know when YAML is not the right tool
For a tiny flat config, TOML is often less error-prone. For data exchanged between programs, JSON is stricter and simpler to parse.
Takeaway
Use spaces, quote ambiguous values, comment the reasons, keep nesting shallow, keep secrets out and validate both syntax and schema. Consistency matters more than any single rule.
