RonzzWikiCowriterAI: New YAML cheatsheet, following the collection's style. AI-assisted (RonzzWikiCowriter) (via create-page on MediaWiki MCP Server)

2026-08-26T11:41:12Z

New YAML cheatsheet, following the collection's style. AI-assisted (RonzzWikiCowriter) (via create-page on MediaWiki MCP Server)

New page

{{Cheatsheet}}

YAML ('''Y'''AML '''A'''in't '''M'''arkup '''L'''anguage) is a human-friendly data format — the de-facto standard for configuration files: GitHub Actions, Docker Compose, Ansible, Kubernetes, and the front matter of [[Cheatsheets:Quarto|Quarto]] documents. It describes plain data with just three building blocks: '''scalars''', '''lists''' and '''maps'''.

New to YAML? The [https://learnxinyminutes.com/docs/yaml/ Learn YAML in Y minutes] tour may interest you.

== Basic example ==

A config file is mostly nested maps and lists. YAML parses to the JSON structure on the right:

{| class="wikitable"
! YAML !! Parsed as (JSON)
|-
|
<syntaxhighlight lang="yaml" copy>
# pancake-service.yaml
service:
name: Pancake API
port: 8080
debug: true

database:
host: localhost
user: admin
password: "s3cret!"

features:
- billing
- search
- loyalty
</syntaxhighlight>
||
<syntaxhighlight lang="json" copy>
{
"service": {
"name": "Pancake API",
"port": 8080,
"debug": true
},
"database": {
"host": "localhost",
"user": "admin",
"password": "s3cret!"
},
"features": ["billing", "search", "loyalty"]
}
</syntaxhighlight>
|}

== Scalars ==

Scalars are the leaf values. YAML guesses their type from the spelling:

{| class="wikitable"
! YAML !! Parsed as
|-
| <syntaxhighlight lang="yaml" inline>name: Pancake API</syntaxhighlight> || string <syntaxhighlight lang="text" inline>"Pancake API"</syntaxhighlight>
|-
| <syntaxhighlight lang="yaml" inline>port: 8080</syntaxhighlight> || integer <syntaxhighlight lang="text" inline>8080</syntaxhighlight>
|-
| <syntaxhighlight lang="yaml" inline>price: 4.50</syntaxhighlight> || float <syntaxhighlight lang="text" inline>4.5</syntaxhighlight>
|-
| <syntaxhighlight lang="yaml" inline>debug: true</syntaxhighlight> || boolean <syntaxhighlight lang="text" inline>true</syntaxhighlight>
|-
| <syntaxhighlight lang="yaml" inline>note: null</syntaxhighlight> || null
|-
| <syntaxhighlight lang="yaml" inline>released: 2024-01-15</syntaxhighlight> || date
|-
| <syntaxhighlight lang="yaml" inline>code: "1234"</syntaxhighlight> || string — quotes force a string
|}

<blockquote>
Null also accepts <syntaxhighlight lang="yaml" inline>~</syntaxhighlight> or an empty value (<syntaxhighlight lang="yaml" inline>note:</syntaxhighlight>). Booleans also accept <syntaxhighlight lang="yaml" inline>True/False</syntaxhighlight>. In YAML 1.1 parsers <syntaxhighlight lang="yaml" inline>yes/no/on/off</syntaxhighlight> are booleans too — see [[#Gotchas|Gotchas]].
</blockquote>

== Strings and quoting ==

Most strings need no quotes at all. Quote the value when its spelling could be misread:

{| class="wikitable"
! Want the string !! Write !! Why
|-
| "Pancakes: the recipe" || <syntaxhighlight lang="yaml" inline>title: "Pancakes: the recipe"</syntaxhighlight> || a colon followed by a space would start a nested key
|-
| "#ffcc00" || <syntaxhighlight lang="yaml" inline>color: "#ffcc00"</syntaxhighlight> || a <syntaxhighlight lang="yaml" inline>#</syntaxhighlight> at the start of a value begins a comment
|-
| "00123" || <syntaxhighlight lang="yaml" inline>zip: "00123"</syntaxhighlight> || leading zeros can parse as octal (YAML 1.1)
|-
| "2024-01-15" || <syntaxhighlight lang="yaml" inline>day: "2024-01-15"</syntaxhighlight> || an unquoted date becomes a date, not a string
|-
| "NO" || <syntaxhighlight lang="yaml" inline>country: "NO"</syntaxhighlight> || YAML 1.1 parsers read <syntaxhighlight lang="yaml" inline>NO</syntaxhighlight> as the boolean <syntaxhighlight lang="text" inline>false</syntaxhighlight>
|-
| " Ada " || <syntaxhighlight lang="yaml" inline>name: " Ada "</syntaxhighlight> || leading/trailing spaces are stripped in plain scalars
|}

'''Single vs double quotes''' — the two styles that guarantee a string:

{| class="wikitable"
! YAML !! Parsed value
|-
| <syntaxhighlight lang="yaml" inline>title: 'It''s ready'</syntaxhighlight> || It's ready — single quotes escape by doubling
|-
| <syntaxhighlight lang="yaml" inline>message: "line1\nline2"</syntaxhighlight> || line1 + newline + line2 — double quotes process <syntaxhighlight lang="text" inline>\n</syntaxhighlight>, <syntaxhighlight lang="text" inline>\t</syntaxhighlight>, <syntaxhighlight lang="text" inline>\"</syntaxhighlight>
|}

== Collections ==

=== Lists ===

A dash and a space, one item per line:

<syntaxhighlight lang="yaml" copy>
features:
- billing
- search
- loyalty
</syntaxhighlight>

Short lists can use flow style with square brackets:

<syntaxhighlight lang="yaml" copy>
features: [billing, search, loyalty]
</syntaxhighlight>

=== Maps ===

Key–value pairs; nesting by indentation:

<syntaxhighlight lang="yaml" copy>
database:
host: localhost
port: 5432
options:
pool: 10
timeout: 30
</syntaxhighlight>

Flow style:

<syntaxhighlight lang="yaml" copy>
database: {host: localhost, port: 5432}
</syntaxhighlight>

=== Lists of maps ===

Configs are often a list of items, each item a map:

<syntaxhighlight lang="yaml" copy>
users:
- name: Ada
role: admin
- name: Bo
role: viewer
</syntaxhighlight>

<blockquote>
Two spaces per level is the convention, but any consistent number of spaces works. '''Tabs are forbidden''' for indentation.
</blockquote>

== Multi-line strings ==

Long text uses block scalars: <syntaxhighlight lang="yaml" inline>|</syntaxhighlight> keeps newlines (literal), <syntaxhighlight lang="yaml" inline>></syntaxhighlight> folds them into spaces:

{| class="wikitable"
! YAML !! Parsed value
|-
|
<syntaxhighlight lang="yaml" copy>
description: |
Line one
Line two
</syntaxhighlight>
||
<syntaxhighlight lang="text" copy>
Line one
Line two
</syntaxhighlight>
|-
|
<syntaxhighlight lang="yaml" copy>
summary: >
Folded lines
become one
paragraph
</syntaxhighlight>
||
<syntaxhighlight lang="text" copy>
Folded lines become one paragraph
</syntaxhighlight>
|}

Chomping indicators control the trailing newline: <syntaxhighlight lang="yaml" inline>|</syntaxhighlight> keeps one (default), <syntaxhighlight lang="yaml" inline>|-</syntaxhighlight> strips it, <syntaxhighlight lang="yaml" inline>|+</syntaxhighlight> keeps all. An explicit number (<syntaxhighlight lang="yaml" inline>|2</syntaxhighlight>) sets the block's indentation.

== Comments ==

<syntaxhighlight lang="yaml" copy>
# a whole-line comment
name: Pancake API # a trailing comment
</syntaxhighlight>

== Anchors and aliases ==

Anchor a block with <syntaxhighlight lang="yaml" inline>&name</syntaxhighlight>, reuse it with <syntaxhighlight lang="yaml" inline>*name</syntaxhighlight>. The merge key <syntaxhighlight lang="yaml" inline><<</syntaxhighlight> copies an anchor's keys into a map:

<syntaxhighlight lang="yaml" copy>
defaults: &defaults
region: eu-west
tier: free

service-a:
<<: *defaults
name: A

service-b:
<<: *defaults
name: B
tier: paid # overrides the merged value
</syntaxhighlight>

Result:

<syntaxhighlight lang="text" copy>
service-a → {region: eu-west, tier: free, name: A}
service-b → {region: eu-west, tier: paid, name: B}
</syntaxhighlight>

<blockquote>
The merge key is a YAML 1.1 feature — supported by PyYAML, Ruby and most JavaScript parsers, but a strict YAML 1.2 parser may reject it.
</blockquote>

== Multiple documents ==

Separate several documents in one stream with a line of <syntaxhighlight lang="yaml" inline>---</syntaxhighlight> (e.g. several Kubernetes objects in one file):

<syntaxhighlight lang="yaml" copy>
---
name: v1
---
name: v2
</syntaxhighlight>

== Gotchas ==

<blockquote>
'''Tabs are illegal in indentation.''' YAML indentation must be spaces; a tab raises an error in most parsers.
</blockquote>

<blockquote>
'''The Norway problem.''' In YAML 1.1 parsers (PyYAML, Ruby, older JS libraries), <syntaxhighlight lang="yaml" inline>yes/no/on/off/y/n</syntaxhighlight> are booleans:

{| class="wikitable"
! YAML !! YAML 1.1 parser !! YAML 1.2 parser
|-
| <syntaxhighlight lang="yaml" inline>country: NO</syntaxhighlight> || boolean <syntaxhighlight lang="text" inline>false</syntaxhighlight> || string <syntaxhighlight lang="text" inline>"NO"</syntaxhighlight>
|}
</blockquote>

<blockquote>
'''Duplicate keys: the last one wins.'''

<syntaxhighlight lang="yaml" copy>
name: Ada
name: Bo
</syntaxhighlight>

parses to <syntaxhighlight lang="text" inline>name: Bo</syntaxhighlight> — most parsers do not complain.
</blockquote>

<blockquote>
'''An empty value is null.''' <syntaxhighlight lang="yaml" inline>note:</syntaxhighlight> (nothing after the colon) is <syntaxhighlight lang="text" inline>null</syntaxhighlight>, not an empty string. For an empty string, write <syntaxhighlight lang="yaml" inline>note: ""</syntaxhighlight>.
</blockquote>

<blockquote>
'''Any JSON is valid YAML.''' YAML 1.2 is a superset of JSON — you can paste JSON straight into a <syntaxhighlight lang="text" inline>.yaml</syntaxhighlight> file.
</blockquote>

== Further reading ==

* [https://yaml.org/spec/1.2.2/ YAML 1.2 spec] — the official specification
* [https://learnxinyminutes.com/docs/yaml/ Learn YAML in Y minutes] — a brisk syntax tour
* [https://yaml-multiline.info/ yaml-multiline.info] — a playground for the block scalars (<syntaxhighlight lang="yaml" inline>|</syntaxhighlight> and <syntaxhighlight lang="yaml" inline>></syntaxhighlight>)
* [[Cheatsheets:Quarto]] — YAML front matter in Quarto documents

Cheatsheets:Yaml - Revision history

RonzzWikiCowriterAI: New YAML cheatsheet, following the collection's style. AI-assisted (RonzzWikiCowriter) (via create-page on MediaWiki MCP Server)