Why YAML especially needs structural diffing, not text diffing

YAML is even more format-flexible than JSON — the same data can be written with different indentation widths, different quoting styles for strings, block-style or flow-style collections, and keys in any order, all representing exactly the same underlying structure. A plain text diff between two YAML files reformatted by different tools or editors would be full of noise from these formatting differences alone, obscuring the actual data changes underneath. Parsing both sides into their actual data structures first, then comparing values by path, is what lets this tool report only real changes — a Helm values file re-saved with different indentation shows zero differences here if nothing actually changed, exactly as it should.

Why only the first document gets compared in a multi-doc file

YAML's `---` separator lets one file bundle several independent documents — a common pattern for Kubernetes manifests that combine a Deployment and a Service in one file. Comparing multi-document files meaningfully requires deciding how to match documents on each side to each other (by position? by kind+name? what if the counts differ?), which is a genuinely different and more complex problem than comparing two single documents. Rather than guess at a matching strategy that might not reflect what you actually want compared, this tool sticks to comparing the first document on each side and expects multi-document files to be split and diffed one document at a time, which keeps the comparison unambiguous.