YAML Anchors, Aliases, Merge Keys, and Safe Expansion

Why YAML needs anchors and aliases

The YAML 1.2.2 specification defines a representation graph, not merely a JSON-shaped tree. A node can have more than one incoming edge, which means the same mapping, sequence, or scalar node can appear at multiple paths. A graph can also contain cycles. The serialization tree must express those relationships in a linear character stream.

On the first serialized occurrence, an anchor names the node. Later alias events refer to that anchor. Anchor names are a serialization detail: a composer can discard the spelling after it has reconstructed the graph. Code must not use an anchor name itself as application data. If a stable identifier matters to the domain, store it as an ordinary mapping value.

contact: &support
  email: support@example.test
  timezone: UTC
primary_contact: *support
after_hours_contact: *support

The two aliases refer to the anchored mapping node. A native constructor might expose shared object identity. Another API might expand aliases into equal but independent objects. A formatter may preserve anchor and alias syntax without constructing application objects. Name the processing layer before claiming that values are “the same object” or “copies.”

Anchor and alias rules that matter in debugging

• An alias points backward. A successful composition requires an alias to refer to a previous node identified by that anchor. A forward alias is unidentified at the point it is read.
• The alias is a node reference. It cannot contain a second mapping or sequence body that modifies the referenced node.
• An anchor may be unused. Giving a node an anchor does not require a later alias.
• Anchor spelling is not content. A processor need not preserve the anchor name after composing the representation graph.
• Names may be reused. The specification says an alias refers to the most recent previous serialized event with that anchor name. Reuse is legal but confusing and should be avoided in human-maintained configuration.
• Scope is a document concern. Do not expect an anchor defined in one document of a YAML stream to be available in a later document.

service: *defaults
defaults: &defaults
  retries: 3

Aliases and merge keys are different features

The merge key document published tag:yaml.org,2002:merge as a YAML 1.1 language-independent type. The key is normally written <<. Its value is a mapping, an alias to a mapping, or a sequence of mappings or aliases. A processor that enables this type inserts keys into the containing mapping.

The yaml library documentation describes merge support as a YAML 1.1 feature and an option, with merge disabled by default for YAML 1.2. Other libraries and applications make different choices. A document can therefore be syntactically accepted while one consumer merges it, another retains an ordinary property named <<, and another rejects it under an application schema.

Merge precedence is easy to misread

base: &base
  color: blue
  retries: 2
regional: &regional
  retries: 4
  timezone: UTC
service:
  <<: [*base, *regional]
  color: green

Under the published merge type, keys explicitly present in service override merged entries. When a sequence supplies several mappings, keys in earlier mappings override matching keys in later mappings. In the example, an enabled implementation would select explicit color: green and take retries from *base, not from *regional. Many readers expect the last entry to win because that is common in command-line overlays, so the sequence deserves tests even when every tool supports merge keys.

A merge does not mean an alias node is being modified. It is a mapping construction rule. Nested mappings are not recursively deep-merged unless a particular application adds another rule. Arrays are not concatenated by the YAML merge type. Describing << as inheritance or a universal deep merge creates expectations the type does not promise.

LiveParse disables merge expansion

LiveParse does not apply merge-key expansion and does not claim to predict how Kubernetes tooling, Docker Compose, CI systems, template engines, or framework-specific configuration loaders will process it. In YAML-to-JSON mode, an unquoted YAML 1.1 << receives the legacy merge tag and stops conversion; quoted YAML 1.1 "<<" and literal YAML 1.2 Core << remain ordinary keys. The YAML Validator checks supported YAML syntax and composition; it is not an application-schema or configuration-semantics validator.

The YAML Formatter parses and reserializes the presentation. It can preserve ordinary anchor and alias relationships, but formatting is not a proof that a target will honor legacy merge behavior. The YAML Viewer labels anchors and alias rows so you can audit references without automatically flattening them.

Why alias construction needs a resource limit

Aliases reduce source repetition, but they can also make constructed data much larger than the input text. An anchored sequence can be referenced many times; a second anchored structure can contain many aliases to the first; later structures can repeat the second. Each layer multiplies the materialized value if a constructor expands every reference into fresh arrays and objects.

unit: &unit [a, b, c, d, e]
row: &row [*unit, *unit, *unit, *unit, *unit]
grid: [*row, *row, *row, *row, *row]

This example is intentionally modest. The same pattern with more aliases and levels can consume substantial memory or CPU. Counting only literal alias tokens is not always enough; a library may estimate how much aliased data will be constructed. The yaml library exposes maxAliasCount for this purpose and warns that disabling the check can permit exponential expansion attacks.

LiveParse's YAML to JSON converter uses a maximum alias count of 50 per YAML document. It reports that aliases were expanded because JSON has no anchor or reference syntax. It also limits input length, node count, depth, and output length, and it rejects a cycle that JSON cannot represent. These limits reduce risk; they do not certify arbitrary YAML as safe for another parser with different features.

Cycles fit a graph but not ordinary JSON

YAML's representation graph can be cyclic. Some constructors can create a native object that refers to itself. Ordinary JSON serialization cannot finish that traversal because JSON has no reference marker. A converter must reject the cycle, replace references according to an application protocol, or use a different graph serialization format.

Do not silently replace a cycle with null or omit the property: either choice changes data. LiveParse stops with a cyclic-alias error during YAML-to-JSON conversion. For acyclic aliases, it expands values within the configured limit and makes the identity loss explicit.

What survives YAML-to-JSON conversion

When an alias points to an ordinary acyclic mapping or sequence, JSON can contain repeated equivalent structures. What does not survive is the fact that those structures shared one YAML node, the anchor's name, and any mutation semantics a native object graph might have. Comments and scalar styles are also absent. Read the complete YAML-to-JSON type conversion guide before treating output as equivalent.

LiveParse rejects alias mapping keys and complex collection keys because JSON object property names must be strings and alias resolution can collapse identity. It stops on !!omap, !!pairs, !!binary, !!set, unresolved tags, and application-specific custom tags rather than stripping semantics. Multiple YAML documents become one top-level JSON array. Non-finite values and finite decimals or timestamps that would lose precision stop conversion before output.

Kubernetes and Compose add separate rules

YAML libraries answer language questions. Kubernetes answers resource questions such as whether apiVersion, kind, metadata, and spec describe a supported API object and whether admission permits it. The official Kubernetes object documentation describes that model. A YAML alias or merge policy in a preprocessing tool does not substitute for API-server or schema-aware validation.

Docker Compose similarly defines services, networks, volumes, configs, secrets, and their field rules in the Compose Specification. A generic YAML parser cannot decide whether a Compose field is misspelled, unavailable in a runtime, or semantically incompatible. Use the target tool's supported validation path after generic syntax checks.

Anchor and merge review checklist

• Does every alias refer to an anchor that appeared earlier in the same document?
• Are anchor names unique in practice, even though the YAML model permits reuse?
• Can the representation graph contain a cycle, and can the target format express it?
• What alias expansion metric and maximum does the deployed library enforce?
• Are input bytes, depth, nodes, output size, processing time, and diagnostics also bounded?
• Does the target explicitly document << merge support and sequence precedence?
• Are any merges expected to be recursive even though the legacy type describes shallow mapping insertion?
• Have you validated the constructed application data, not just the formatted YAML text?

For a final data check, inspect expanded compatible output in the JSON Formatter and Validator. For contrast, XML references such as entity declarations have different syntax and security behavior; the XML Validator deliberately disables DTD processing rather than pretending YAML alias limits cover XML expansion risks.