YAML Sorter
Recursively sort YAML mapping keys alphabetically — comments and multi-document streams are preserved.
Comments stay attached to their keys and move with them; list order is preserved (only nested mapping keys sort).
How YAML key sorting works
This tool parses your YAML and sorts the keys of every mapping alphabetically — at the top level and inside every nested mapping. Sequences (lists) keep their order since order is usually meaningful, but a list item that is itself a mapping has its keys sorted too. Crucially, it uses a comment-preserving parser (yaml, the eemeli CST library), so your comments survive the sort — they stay attached to their keys and move with them — and multi-document streams (separated by ---) are each sorted. That makes it safe for real config files (Docker Compose, CI pipelines, Kubernetes manifests), where a js-yaml-based sorter would silently delete every comment. Everything runs locally in your browser. For formatting without reordering, try the YAML Formatter.
Built and maintained by Meet Shah · Last updated
What this tool is used for
- Sorting keys so two YAML files can be compared meaningfully.
- Producing a canonical form before diffing two manifests.
- Tidying a config whose keys have accumulated in arbitrary order.
- Making a long manifest easier to scan by grouping keys predictably.
- Checking whether two configs hold the same keys in a different order.
Frequently Asked Questions
- Why sort YAML keys?
- To make diffs meaningful. Two people editing the same config append keys in different places, and a diff full of moves hides the one real change. Sorting canonicalises the order, which is the same reason lockfiles are sorted.
- Does sorting change what the YAML means?
- Not for mappings, which are unordered by specification. Sequences are a different matter entirely — their order IS the data, so list items are never reordered. Sorting a list of pipeline steps would change what the pipeline does.
- Are comments preserved?
- They are, and it is the hardest part of doing this correctly. Comments are not part of the parsed data structure, so a naive parse-and-re-emit loses every one — which is a silent, unrecoverable loss in a config file where the comments explain the values.
- Does sorting affect anchors and aliases?
- It can. An alias must appear after the anchor it references, so reordering keys can move a reference above its definition and break the document. Anchors are the one YAML feature where key order genuinely matters.
- Should sorted YAML be enforced in CI?
- It is worth considering for large shared config — a check that fails on unsorted keys removes an entire category of merge conflict. The cost is that a semantically meaningful grouping, such as related settings kept together, is lost to alphabetical order.
Common errors and gotchas
- Sorting a file where key order was meaningful, such as an ordered pipeline of steps.
- Sorting list items, which changes data rather than tidying it — only mapping keys are safe.
- Losing comments, which most YAML round-trips discard.
- Expanding anchors and aliases during the sort, which duplicates data.
- Assuming the result validates against the same schema, when a sequence-based one may not.