YAML Reference

YAML Reference

YAML is popular because humans can scan it quickly, but that same friendliness hides structural rules that break fast when indentation or nesting drifts. This reference is for the practical side of YAML: writing valid mappings and lists, understanding scalars, and using anchors or aliases when a config repeats itself.

If you searched for yaml examples, yaml sample, YAML syntax, or YAML reference anchor, this page is meant to be the compact answer layer. It explains the pieces you need to write working configuration, not just the formal grammar.

How to use this reference

1. Decide whether you are writing mappings, sequences, or both.
2. Keep indentation consistent from the start. YAML errors are often structure errors, not content errors.
3. Use anchors and aliases only when repetition is real. Readability still matters more than clever reuse.

YAML building blocks

| Nested mapping | `database:

host: db` | Groups related settings |

| Sequence of mappings | - name: web | Common in services and pipeline steps |

| String scalar | env: production | Simple text value |

| Boolean scalar | enabled: true | Real boolean, not a string |

| Anchor | defaults: &defaults | Reuse a block elsewhere |

| Alias | <<: *defaults | Merge or reuse anchored values |

A practical YAML example

```yaml

app:

name: billing-api

port: 8080

features:

• invoices
• refunds

database:

host: db.internal

ssl: true

```

This example shows why YAML is appealing for configuration. The shape is readable at a glance. But it is also a reminder that structure is carried by indentation, not braces. Two accidental spaces can change meaning or break the file completely.

YAML syntax rules that trip people up

YAML is often described informally as “human-friendly,” and that is directionally true. But friendliness is not looseness. Keys and nesting still obey strict structure. Some values that look like plain strings can be interpreted differently by tools depending on schema or parser behavior. That is why many teams quote values when ambiguity would be costly.

A practical YAML reference should keep these points visible:

• indentation defines scope
• tabs are usually a bad idea for YAML indentation
• lists start with -
• mappings use key: value
• nested structures must remain visually aligned

Anchors, aliases, and references

When people ask about a YAML reference, they often mean a YAML anchor or alias. Anchors let you name a block, and aliases let you reuse it.

```yaml

defaults: &defaults

retries: 3

timeout: 30

job:

<<: *defaults

timeout: 60

```

This pattern is useful in CI pipelines, deployment manifests, or service definitions where several blocks share the same defaults. It is also a good example of where YAML differs from JSON. YAML can express this kind of reusable structure directly, while plain JSON usually cannot without a higher-level convention.

YAML is not “just JSON without braces”

YAML can represent many of the same data shapes as JSON, but it is not simply relaxed JSON. It has its own syntax, merge features, multiline styles, and parser-specific edge cases. That is why copying JSON habits straight into YAML can create subtle errors. For example, indentation now carries the structure, and anchors introduce reuse patterns that JSON does not natively provide.

This is also why it helps to keep a JSON reference nearby. YAML is excellent for human-edited configs. JSON is excellent when strict machine-oriented structure is the priority.

Common mistakes to avoid

Common questions

What does “YAML is a human...” usually mean?

It comes from the recursive name “YAML Ain't Markup Language.” In practical terms, it signals that YAML is meant for data representation, especially human-readable configuration, not document markup.

What is the fastest way to write valid YAML examples?

Start with a simple mapping or list, keep indentation consistent, and only nest when the shape is clear.

How do YAML anchors work?

An anchor names a block with &name, and an alias reuses it with *name. Some tools also support merge keys like <<: *name.

When should I use YAML instead of JSON?

Use YAML when humans will edit the configuration frequently and readability matters. Use JSON when strict, explicit machine-oriented structure is the priority.

Related references

Compare this page with the JSON reference for stricter structured data, the regex reference for pattern matching inside config-like text, the Bash reference when config values are wired into shell scripts, or the VS Code shortcut reference when you edit configuration files heavily inside the editor.

Keep readability above cleverness

YAML gives you anchors, aliases, multiline forms, and merge patterns, but readability should stay the priority. A short, repeated block is often better than an indirect one that forces the next reader to jump around the file. Use reuse features when they reduce real maintenance cost, not just because the syntax allows them.