YAML Anchor, Aliases and Merge Keys

(Written by: Tom Klingenberg (Ktomk); Nov 2020)

Serializing data in YAML is kind of common these days, especially configuration data. JSON is a similar, perhaps even more popular, format (and almost[!] a subset of YAML 1.2).

Some of YAML's properties not in JSON are anchors, aliases and merge keys that can work well together. These allow references and mixins for hashes (not sequences a.k.a. arrays) and are common to reduce repetition of same configuration directives that some files/systems tend to and/or sometimes just because one can (TIMTOWTDI).

In/from/by the YAML specification:

YAML Anchor
YAML 1.2 (3rd Edition) Anchors and Aliases
YAML 1.1 Anchors and Aliases
YAML 1.0 4.3.6. Anchor
YAML Alias
YAML 1.2 / 1.1; see above Anchors and Aliases
YAML 1.0 4.4. Alias
YAML Merge Key
<< : *<anchor-name> (one; or:)
<< : [ *<anchor-name>, *<anchor-name>, ... ] (sequence of: [none,] one or multiple)
YAML 1.1 Working Draft Merge Key Language-Independent Type

Anchors need to be before aliasing (e.g. in an alias or merge key), can remain unused and can be re-defined, last one wins at the time of use (flow is from top to bottom).

Example-YAML with Aliases, References and Merge Keys taken from the Merge Key working draft:

- &CENTER { x: 1, y: 2 }
- &LEFT { x: 0, y: 2 }
- &BIG { r: 10 }
- &SMALL { r: 1 }

# All the following maps are equal:

- # Explicit keys
  x: 1
  y: 2
  r: 10
  label: center/big

- # Merge one map
  << : *CENTER
  r: 10
  label: center/big

- # Merge multiple maps
  << : [ *CENTER, *BIG ]
  label: center/big

- # Override
  << : [ *BIG, *LEFT, *SMALL ]
  x: 1
  label: center/big

Caveat: YAML Aliases and Schema-Validation

Schema-validation of a YAML document is only possible when all references and merge keys are represented. However, it is not that every schema-validator is able to keep the error information aligned to the original, pointing to the right, invalid line/offset or definition.

Schema-validation in the Intellij platform does not have this issue. Expect others to be broken, test before use.


YAML parsing is normally considered hard (complicated as the syntax is complex). With all due respect, personally I can adhere to that in part, the YAML specification appears to be at (isolated) places hard to read despite me self-imagined being trained over decades into reading publicly available specifications (in not my first language). To be fair, it is one of the very few specs that has graphics and by the nature of its formulation, compilers are hard to read as well.

Caveat: Support of Merge Keys

Support in (YAML versions is different / is different per) specific YAML versions:


No idea when removal of Merge Keys will apply. Systems practically support YAML Merge Key/s, but it needs verification on a case to case basis.

A YAML (file) is used against a specific system? Good to test first if Merge Keys are supported.

Will Merge Key/s ever be removed? I wonder that as it has become part of the API, deprecation only helps book-keeping, and later then for history.


Index of Names