How to use the yaml diff
- Paste your original YAML into the Original YAML text area.
- Paste the modified YAML into the Modified YAML text area.
- The yaml diff results update automatically as you type or paste.
- 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.yamlfiles 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:
| Input | Parsed Value | Type |
|---|---|---|
true, True, TRUE | true | Boolean |
false, False, FALSE | false | Boolean |
null, Null, ~, empty | null | Null |
42, -1 | 42, -1 | Integer |
3.14, .5 | 3.14, 0.5 | Float |
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
| Example | Input | Result |
|---|---|---|
| Changed value and added key | Original YAML: name: Alice / age: 30; Modified YAML: name: Bob / age: 30 / role: admin | name: changed from "Alice" to "Bob", role: added "admin" |
| Array modification | Original YAML: items: / - apple / - banana; Modified YAML: items: / - apple / - cherry | items[1]: changed from "banana" to "cherry" |
| Nested mapping change | Original YAML: server: / host: localhost / port: 8080; Modified YAML: server: / host: 127.0.0.1 / port: 8080 | server.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.