What the XML Merge Tool does
Load a base document and an incoming document from XML files or pasted text. The tool checks their roots, applies the selected child-element merge strategy, and shows a merged XML tree with a categorized report.
The roots must have the same local name and namespace URI, or both have no namespace. The tool parses, merges, and exports the documents in your browser; the local implementation does not upload the source documents.
Choose a merge strategy
- Append (incoming children added after base children) adds incoming root children after the base children. It does not need an identity rule.
- Replace (matched elements substituted wholesale) uses an identity rule to find one base child and replaces that child with the incoming element. An unmatched value adds a child; an ambiguous match stays unchanged and is flagged unresolved.
- Key-based merge (matched elements merged recursively) combines matching elements, their attributes, meaningful direct text, and child elements according to the selected policies. Incoming elements without a base counterpart are added. Elements without an identity value are appended and flagged unmatched; ambiguous matches are left unmerged and flagged unresolved.
Matching is based on identity values, not sibling position. Replace groups candidate children by local name. Key-based merge groups them by tagName, so do not assume identical grouping for every namespace-prefix arrangement.
Set identity and conflict policies
Replace and Key-based merge require an identity input. Choose Selected attribute, Direct child element, or Supported XPath expression. The supported expressions are @attr, name(), local-name(), a direct-child name for its text, and childName/@attr.
Set Sibling-order policy, Attribute conflict policy, and Text-node conflict policy. Text conflicts concern meaningful direct text nodes. For matched elements, each conflict can use incoming values, keep base values, or be flagged unresolved.
Set Comment policy, CDATA policy, XML declaration policy, and Namespace-prefix policy. Comment processing applies to direct child comments. In append mode, Incoming only allows incoming comments but does not remove existing base comments; Base only ignores incoming comments, and Drop all drops comments handled by that strategy.
How to merge two XML documents
- Enter both sources as pasted XML or choose them with the file browse/drop controls.
- Choose a value in Child-element merge strategy. If you choose replace or key-based merge, complete the required identity field.
- Choose the sibling-order, conflict, comment, CDATA, declaration, and namespace-prefix policies.
- The merge runs automatically when both documents are valid and whenever a setting changes.
- Review Merged tree preview, the result counts, and the categorized report.
- Select Clear all to reset the loaded sources and result workspace.
Validation, matching, and report limits
The merge stops when both sources are not loaded, either source is not valid XML, the root local names or namespace URIs differ, or a non-append strategy has an empty identity input. It does not guess a match from position. A value with several base matches remains unchanged and is reported as unresolved; a value with no base match is added, while an identity value that cannot be computed is reported as unmatched.
The report includes a generated time, source names, selected options, counts, and categorized added, replaced, unresolved, and unmatched entries. Its locations are XPath-like, such as /Root[1]/Items[1]/Item[3]/@id. Append mode does not add report entries for every incoming text, CDATA, or comment node, so treat the report as the events recorded by the implementation rather than a complete log of every appended node.
Preview and export results
After a successful merge, inspect the rendered tree and report. Export merged XML downloads merged.xml. Export merge report (JSON) downloads merge-report.json.
Frequently Asked Questions
How is this different from XML Diff?
XML Diff reports structural differences without changing either document. This tool combines a base and incoming document into one output tree using a selected strategy and exports the merged result.
What counts as a compatible root?
Both root elements must share the same local name and namespace URI, or both have no namespace. Otherwise, the merge is blocked.
What is a key-based child-element merge?
It computes an identity value for each grouped child with the selected attribute, direct child, or supported XPath-style rule. Matching elements are merged recursively; elements without a counterpart are added, and elements without an identity value are flagged unmatched. Ambiguous base matches are flagged unresolved and left unmerged.
What XPath expressions are supported for identity?
The supported subset is for identity values, not general querying: @attr, name(), local-name(), a direct child name for its text, and childName/@attr. It is narrower than full XPath 1.0.
What happens to comments, CDATA, and the XML declaration?
Each has a selectable policy. Comments can be kept from both sources, base only, incoming only, or dropped; CDATA can stay CDATA or become plain text; and the declaration can come from the base, come from the incoming document, or be omitted. Comment handling applies to direct child comments, and append mode does not remove base comments when Incoming only is selected.
Does this tool diff, convert to JSON, or silently merge nodes?
It creates merged XML rather than a compare-only diff, does not perform plain text concatenation, and does not convert XML to JSON. Append mode needs no identity rule; replace and key-based merge do. The report records categorized events, but append mode does not report every added text, CDATA, or comment node.