Xerobit

YAML Diff: Compare Two YAML Documents Structurally

Paste two YAML documents to compare them structurally. This yaml diff tool parses both inputs, walks the resulting trees and lists every added, removed or changed key with its path. It runs entirely in your browser so nothing is uploaded anywhere.

The base document for comparison.

The document to compare against the original.

Differences

No differences found.

How to use the yaml diff

  1. Paste your original YAML into the Original YAML text area.
  2. Paste the modified YAML into the Modified YAML text area.
  3. The yaml diff results update automatically as you type or paste.
  4. Review the list of added, removed and changed keys with their exact paths.

How the structural comparison works

A structural yaml diff compares the parsed data trees rather than raw text lines. Both documents are parsed into nested objects and arrays. The tool then walks both trees simultaneously, tracking the current path such as server.port or items[0].

When a key exists only in the original tree it is marked as removed. When a key exists only in the modified tree it is marked as added. If a key exists in both but its scalar value differs, it is marked as changed. This approach means that reordering mapping keys or changing whitespace does not produce false positives.

Supported YAML subset

The built-in parser handles the most common YAML 1.2 features used in configuration files:

  • Block mappings (key-value pairs) and block sequences (lists starting with -)
  • Flow collections using brackets [] and braces {}
  • Plain scalars, single-quoted strings and double-quoted strings with escape sequences
  • Block scalars using literal | and folded > indicators
  • Comments starting with #

Anchors (&), aliases (*), tags (!) and merge keys (<<) are intentionally rejected with an explicit error message rather than producing incorrect results. Multi-document streams separated by --- are also not supported. For full YAML 1.2 compliance, consider converting to JSON first using a dedicated YAML to JSON tool.

Common use cases

Comparing YAML files is a frequent task when managing infrastructure and application settings. Here are typical scenarios where a yaml diff saves time:

  • Kubernetes manifests: Spotting unintended changes between deployment versions before applying them to a cluster.
  • CI/CD pipelines: Verifying that environment variable overrides were applied correctly across staging and production configs.
  • Helm values: Checking what changed between default values.yaml files and custom overrides.
  • Docker Compose: Comparing service definitions after refactoring a compose file.

Because this tool runs locally in the browser, it is safe to use with sensitive configuration files containing credentials or internal hostnames.

Why not just use a text diff?

A standard line-by-line text diff treats YAML as plain text. This causes problems because YAML allows multiple representations of the same data. For example, adding a comment, changing indentation style or reordering keys will show up as differences in a text diff even though the parsed data is identical.

A structural yaml diff parses both documents first, normalizing these variations away. You only see meaningful changes to the actual data. If you need to compare other structured formats, tools like JSON diff and XML diff apply the same principle to their respective syntaxes.

Reference: scalar resolution rules

The parser resolves unquoted scalars according to YAML 1.2 Core Schema rules. Understanding these helps explain why certain values match or differ:

InputParsed ValueType
true, True, TRUEtrueBoolean
false, False, FALSEfalseBoolean
null, Null, ~, emptynullNull
42, -142, -1Integer
3.14, .53.14, 0.5Float
hello world"hello world"String

Quoted scalars (single or double quotes) are always treated as strings regardless of content. During comparison, the string "42" and the integer 42 are considered different values, while 1 and 1.0 are the same number. Integers beyond 2^53 are compared digit by digit, and duplicate keys in either document are reported as errors. Arrays are compared by position, so inserting one item near the start of a long list reports every later index as changed.

Worked examples

ExampleInputResult
Changed value and added keyOriginal YAML: name: Alice / age: 30; Modified YAML: name: Bob / age: 30 / role: adminname: changed from "Alice" to "Bob", role: added "admin"
Array modificationOriginal YAML: items: / - apple / - banana; Modified YAML: items: / - apple / - cherryitems[1]: changed from "banana" to "cherry"
Nested mapping changeOriginal YAML: server: / host: localhost / port: 8080; Modified YAML: server: / host: 127.0.0.1 / port: 8080server.host: changed from "localhost" to "127.0.0.1"

FAQ

Does this yaml diff tool upload my data?

No. All parsing and comparison happens locally in your browser. Your YAML documents are never sent to any server.

Why do I get an error about anchors or aliases?

The built-in parser supports a practical subset of YAML 1.2. Anchors, aliases, tags and merge keys are explicitly rejected to prevent silent misinterpretation of your data.

Can I compare multi-document YAML streams?

No. The parser expects a single YAML document per input. Streams separated by --- markers are not supported.

How are arrays compared?

Arrays are compared element by element using their index. If one array has more elements than the other, the extra elements are reported as added or removed.

Is the comparison order-sensitive for mapping keys?

No. Mappings are unordered by definition in YAML. Changing the order of keys without changing their values produces no differences.

What if my YAML is invalid?

The parser will return an error message indicating the line and nature of the syntax problem. You can use a YAML validator to debug complex issues before comparing.