Duplicate anchor names in YAML 1.2 create inconsistent alias resolution across parsers

Answer the questions first

1. Should duplicate anchors be an error by default? – No. The YAML 1.2 specification does not forbid duplicate anchor names, so most libraries allow them. However, silent overrides can corrupt configuration files, so many projects prefer to treat duplicates as a warning or error.

2. If duplicates are allowed, what deterministic rule should be documented? – A consistent rule is essential for cross‑tool pipelines. Two common conventions exist:

• First‑wins – the alias refers to the first anchor definition encountered.
• Last‑wins – the alias refers to the most recent anchor definition.

Both are used in practice (SnakeYAML first‑wins, ruamel.yaml last‑wins). Documenting one of these (or allowing the user to choose) removes ambiguity.

3. How should user‑facing workflows signal ambiguity without breaking existing docs? – Provide a linting or validation step that emits a warning when duplicate anchors are detected. Offer a configuration flag to elevate the warning to an error if strictness is required. Existing documents will continue to parse, but developers will be alerted to potential overrides.

Likely explanation

The YAML 1.2 spec intentionally leaves duplicate anchor resolution unspecified, which means parser authors are free to choose a strategy. SnakeYAML registers anchors in insertion order and resolves aliases to the first registered & definition. ruamel.yaml keeps the latest & definition and resolves aliases to that one, but can be switched to error mode. libyaml’s behaviour is implementation‑defined and can vary with parser flags or document structure.

Confirmed facts (from library behaviour)

• SnakeYAML – first‑wins, optional fail‑on‑duplicate flag.
• ruamel.yaml – last‑wins by default, warns on duplicates, optional error mode.
• libyaml – no normative rule; precedence may depend on parser configuration.

Steps for your project

1. Audit – Run a small script that parses your YAML files with all three libraries and records which anchor each alias resolves to. Compare the results to identify any divergences.

   # Example (Python)
   import yaml
   with open('config.yaml') as f:
       data = yaml.safe_load(f)
   print(data)
   

2. Choose a rule – Decide whether you want first‑wins or last‑wins for your configuration files. Document this choice in your style guide.
3. Enforce – Add a linting step (e.g., using yamllint with a custom rule) that flags duplicate anchors. If you want stricter enforcement, configure the library to raise an exception on duplicates.
4. Communicate – Update your CI pipeline to emit warnings for duplicate anchors and provide a migration path for any files that would be affected by a change in resolution strategy.

Missing diagnostic detail

Do you need the parser to preserve the current behaviour of your existing configuration files, or would you prefer to enforce stricter duplicate‑anchor detection across all tools?