TopolearnEvery YAML file, from a CI pipeline to a Kubernetes manifest, is these two structures nested.
A YAML document describes data built from three kinds of nodes: mappings (key/value pairs, like a dict or JSON object), sequences (ordered lists) and scalars (strings, numbers, booleans, null).
A mapping writes each pair as key: value, one per line. The space after the colon is required: key:value is a single string, not a pair.
A sequence writes each item on its own line after - (dash and space).
Indentation shows nesting. Child nodes are indented more than their parent, using spaces only: tabs are not allowed for indentation. The amount is up to you (two spaces is the common style) but siblings must line up exactly.
A sequence that is the value of a mapping key may be indented or written at the same level as the key; both of these are valid and mean the same:
steps:
- build
- test
steps2:
- build
- test# starts a comment that runs to the end of the line; it must be preceded by whitespace when it follows a value.
Keys in one mapping must be unique, and mappings are unordered in the data model, although most parsers keep the file order.
Example
# a typical config file
name: web-app
version: 3
replicas: 2 # comments start with #
ports:
- 80
- 443
owner:
team: platform
email: platform@example.com
env:
- name: LOG_LEVEL # a sequence of mappings
value: info
- name: REGION
value: eu-west-1
# parsed (as JSON):
# {"name": "web-app", "version": 3, "replicas": 2, "ports": [80, 443],
# "owner": {"team": "platform", "email": "platform@example.com"},
# "env": [{"name": "LOG_LEVEL", "value": "info"}, {"name": "REGION", "value": "eu-west-1"}]}Remember
- key: value pairs form mappings; - item lines form sequences
- Indent with spaces only; siblings must align
- A space is required after the colon and the dash
Watch out for
- Indenting with a tab, which is a syntax error in YAML even though it may look aligned in the editor.