Sequence
yaml.org 1.2.2 §10.1- item (block) | [item, item, ...] (flow)
A YAML sequence is an ordered list of nodes equivalent to a JSON array. Block style uses a leading dash and space (- item) for each element. Flow style uses JSON array syntax [a, b, c]. Sequences can nest sequences and mappings to any depth.
Description
Sequences represent ordered collections. YAML provides two syntactic styles that produce identical in-memory representations:
Block style uses one element per line, each prefixed with '- ' (dash-space). Indentation under the parent key groups the elements. This is the dominant style in Kubernetes manifests and CI/CD configs.
Flow style uses comma-separated values inside square brackets, identical to JSON arrays. Flow style is more compact for short lists of simple scalars.
Nesting: sequences can contain mappings (a list of objects), other sequences, or any scalar type. Kubernetes containers is a sequence of mappings. env within each container is itself a sequence of mappings.
Empty sequence: use [] in flow style or omit elements in block style. An explicit empty block sequence is not possible without the flow notation.
Ordering: YAML sequences preserve insertion order. Unlike mappings, the order of sequence elements is significant and guaranteed by the spec.
Examples
| Label | Value |
|---|---|
| Block sequence | ports: - 8080 - 8443 |
| Flow sequence | tags: [web, api, v2] |
| Empty sequence | items: [] |
| Sequence of mappings | containers: - name: app image: app:1.0 - name: sidecar image: proxy:2.1 |
| Nested sequence | matrix: - [1, 2, 3] - [4, 5, 6] |
| Mixed types | values: - 42 - hello - true - null |
| Kubernetes env list | env: - name: PORT value: "8080" - name: LOG_LEVEL value: info |
Common Gotchas
The dash-space (- ) must be followed by a space; a bare dash without space is part of a plain scalar
Indentation of list items must be consistent within the sequence; mixing 2-space and 4-space under the same parent causes a parse error
Flow sequences [a, b] and block sequences are semantically identical – choose one style and be consistent
A sequence containing a single item still needs the dash: '- item' not just 'item'
Trailing commas in flow sequences [a, b,] are not allowed in YAML 1.2 (allowed in YAML 1.1 with some parsers)
Sequence-under-key indentation: the '- ' can be at the same indent level as the key or indented further; both are valid but inconsistency breaks readability