Overview
Introduction
Two YAML documents can be semantically identical, same keys, same values, and still diff noisily because of key order, inconsistent quoting, or a comment one contributor added and another didn't. This tool produces a single, predictable serialization of a document's underlying data, so equivalent documents converge on the same text.
It's built specifically for version-control-friendly config: commit this tool's output instead of hand-formatted YAML, and future diffs reflect actual data changes rather than incidental formatting differences.
What Is YAML to Canonical Normalizer?
A canonical YAML normalizer parses a document into its underlying value (which already discards comments, since they aren't part of YAML's data model), recursively sorts every mapping's keys alphabetically using this site's YAML Sorter logic, and re-serializes the result with the yaml package's default block-style stringifier.
The word "canonical" here is used in the everyday sense, a single, consistent, reproducible form, not YAML 1.1's formal, stricter, tag-annotated canonical form spec, which this tool does not implement or claim to.
How YAML to Canonical Normalizer Works
The input is parsed into a plain JavaScript value. That value is walked recursively: every mapping's keys are sorted with locale-aware string comparison before its values are processed (also recursively), while sequences are left in their original order, since sequence order is meaningful in a way mapping key order isn't.
The sorted value is re-serialized with 2-space indentation, preferring plain (unquoted) scalars except where quoting is syntactically required (the yaml package's default stringify behavior already handles this correctly), and any \r\n or \r line endings in the result are normalized to \n.
When To Use YAML to Canonical Normalizer
Use it before committing generated or hand-edited YAML to version control, so the committed form is consistent regardless of who or what produced it.
It's also useful for confirming two YAML documents are truly equivalent: normalize both and diff the results, if they match, the documents represent the same data regardless of original formatting.
Often used alongside YAML Sorter, YAML Formatter & Prettifier and YAML Merge Tool.
Features
Advantages
- Produces identical output for semantically-equal documents regardless of original key order, quoting style, or comments.
- Reuses this site's exact YAML Sorter logic for key sorting, rather than a second, potentially inconsistent implementation.
- Never reorders sequences, preserving order where it's actually meaningful.
- Runs entirely client-side, so configuration data never leaves your browser.
Limitations
- This is not YAML 1.1's formal "canonical form" (the strict, tag-annotated representation defined by the spec for interoperability testing); this tool's "canonical" means consistent and diffable, not spec-compliant with that stricter definition.
- Comments are always stripped, since the transformation fully parses and re-serializes the document, there's no way to preserve them through that round trip.
- Anchors, aliases, and explicit YAML tags in the source document aren't specially preserved or re-emitted in their original form; the output reflects the parsed value's structure, not the original document's exact syntactic features.
Examples
Best Practices & Notes
Best Practices
- Adopt this as a pre-commit step for shared YAML config if diff noise from formatting differences has been a recurring problem for your team.
- Don't rely on this tool to preserve comments, if a comment documents something important, keep that documentation somewhere that survives normalization (a README, a schema description) instead.
- Pair with YAML Validator first if you're not sure the input is valid YAML to begin with.
Developer Notes
This tool is intentionally thin: it imports sortValue directly from the yaml-sorter tool's lib module (exported specifically so it could be reused here rather than reimplemented) with sortArrays fixed to false, then pipes the result through toBlockYaml and a final \r\n/\r to \n normalization pass. No YAML 1.1 canonical-form tag annotation, explicit type tags, or anchor/alias re-emission logic is implemented, deliberately, since that's a materially different (and rarely needed) feature.
YAML to Canonical Normalizer Use Cases
- Normalizing YAML config before committing it to version control for consistent, low-noise diffs
- Confirming two differently-formatted YAML documents represent the same underlying data
- Producing a consistent baseline form of generated YAML for snapshot testing
- Cleaning up hand-edited YAML with inconsistent key ordering across a team
Common Mistakes
- Assuming this implements YAML 1.1's strict, spec-defined "canonical form" (with explicit tags and a specific quoting style), it doesn't; this tool's normalization is a practical, diff-friendly convention, not that formal spec.
- Expecting comments to survive normalization, they don't, since the document is fully parsed and re-serialized.
- Normalizing a document where sequence order was accidentally meaningful (like a prioritized list) and being surprised it stayed in that same order, sequences are never reordered, only mapping keys are.
Tips
- Run this on both sides of a comparison before using YAML Diff, so the diff reflects real value changes, not incidental formatting differences.
- If you need array sorting too (for genuinely unordered scalar lists), use YAML Sorter directly with its array-sorting option enabled instead.
- Combine with YAML Validator in your workflow: validate first, then normalize, so parse errors are diagnosed before normalization masks them.