How to merge YAML sources
Load at least two valid YAML sources by dropping files, browsing for multiple files, or pasting YAML text. A source can contain one document or a ----separated multi-document stream. When pasting, enter an optional source name before clicking Add source.
- Check the source list order. It is the order in which sources were added, and it affects First source wins, Last source wins, and Concatenate (append in source order). Use each source's Remove control to delete one source, or click Clear all to reset the list.
- Choose the document-pairing and merge-rule options that match your sources.
- Set the construct policies for anchors, aliases, merge keys, comments, and document boundaries.
- Review the merged result as soon as at least two valid sources are loaded.
- Review the YAML preview, Every conflict & resolution, and Unsupported / logged constructs.
- Click Export merged YAML to download
merged.yaml, or click Export merge report (JSON) to downloadyaml-merge-report.json.
Document pairing for multi-document streams
Use Pair by document position across streams (source counts must match) to merge document 1 from each source together, then document 2, and so on. All sources must have the same document count; the result can contain multiple merged documents.
Use Treat each source as exactly one document only when every source contains one document. A multi-document source blocks the merge under this option.
Choose merge rules
Deep (recursive merge at every level) merges nested mappings. Shallow (top-level keys only) resolves a nested-mapping conflict by precedence instead of merging its child keys.
Last source wins or First source wins controls scalar and type conflicts and replacement sequences. The null policy decides whether explicit null is a normal value or is treated as absent.
Choose a global sequence strategy: Replace (precedence picks one sequence), Concatenate (append in source order), Union (dedupe by full value, order preserved), or Merge by key (sequences of mappings). Add per-path overrides with dot notation such as items or a.b.list. If no key field is configured for the whole key-merge strategy, that sequence falls back to replacement using precedence. Items that lack the configured key remain as ungrouped raw items in the key-merge output.
Set the construct policy
- For anchors and aliases, choose Expand to value before merge, log every occurrence or Block the merge if any anchor or alias is present.
- For recognized merge-key syntax in block mappings, choose Treat as pre-resolved before this tool's merge, log every occurrence or Block the merge if any source uses <<. A
<<entry inside a flow mapping is parsed as an ordinary key and is not reported as a merge-key event. - For comments, choose Proceed, log that comments are discarded (never preserved on output) or Block the merge if any source contains comments.
- For document boundaries, choose Allow multi-document sources, apply the pairing rule above or Block the merge if any source has more than one document.
Review conflicts, logs, preview, and exports
After a successful merge or a policy-blocked run, the result workspace appears. The result is re-serialized as YAML text. Every conflict & resolution shows the path, candidate values, and selected resolution. Unsupported / logged constructs records the source, line where available, construct, policy, and outcome for anchors, aliases, recognized block-mapping merge keys, comments, and document boundaries.
Limitations and blocked runs
- Automatic merging waits until at least two valid sources are loaded.
- Fix or remove sources reported as malformed or unsupported YAML. The page uses a self-contained YAML subset parser, so some YAML syntax may be rejected.
- Different document counts block Pair by document position across streams (source counts must match).
- Multi-document sources block Treat each source as exactly one document.
- Strict construct policies can reject a source and block the merge.
- Malformed sources, pairing mismatches, and strict policy violations stop normal result generation. The tool merges YAML structure; it does not diff versions or validate against JSON Schema, OpenAPI, or another external schema. Source files are not mutated.
Privacy & Security
Parsing, merging, and export happen locally in the browser. The implementation does not upload source content or require an account, and source files are not mutated.
Frequently Asked Questions
How is this different from YAML Diff?
YAML Diff reports structural differences between two YAML documents - it does not produce a combined document. This tool does the opposite: it combines two or more YAML sources into one merged document using rules you control. If you want to see what changed between versions, use YAML Diff; if you want to combine layered configuration files into one, use this tool.
What happens to YAML anchors, aliases, and merge keys (<<) during a merge?
Plain YAML anchors and aliases are resolved to their full value before the merge logic runs. Choose Expand to value before merge, log every occurrence to proceed, or Block the merge if any anchor or alias is present. Recognized << merge-key syntax in block mappings is pre-resolved and logged or blocked according to the selected policy. A flow-mapping << entry is treated as an ordinary key and is not emitted as a merge-key event.
Are YAML comments preserved in the merged output?
No. Comments are not preserved through parse, merge, and re-serialize. Choose whether to log that comments were discarded or block the merge when a source contains comments.
How does document pairing work for multi-document YAML streams?
If a source is a multi-document stream separated by ---, choose Pair by document position across streams (source counts must match) or Treat each source as exactly one document. The first option requires equal document counts; the second rejects multi-document sources.
How does sequence (array) handling work?
You set a global default - replace, concatenate, union by full value, or merge sequences of mappings by a chosen key field - and can override it for specific paths. Order is preserved in every mode; only key-based merge groups items by key, and even then existing relative order is kept. Replace picks one sequence by precedence like a scalar conflict; concatenate appends every source's sequence in source order; union deduplicates by deep value equality. If no key field is configured for key merging, the whole sequence falls back to replacement; an item missing the configured key remains an ungrouped raw item.
Does this tool validate my YAML against a schema?
No. It parses and merges YAML structure only - it does not validate against JSON Schema, OpenAPI, or any external schema. That is out of scope; use a dedicated schema validator for that.