User Guide

Introduction

XML Data Compare provides a readily customisable solution that identifies and marks the differences between any two XML data files that share the same root element. It is optimised for XML containing structured data, as opposed to XML documents containing more narrative free-flowing content.

An understanding of XSLT is not required for XML Data Compare. The comparison features of XML Data Compare are customised using simple XPath expressions within a configuration file; these XPaths identify parts of the input XML that require special processing. XML Data Compare's primary use is as a toolkit for integration into other systems or applications using a REST interface.

This user guide introduces you to the XML Data Compare product, providing a high-level product description along with a look at the main features and concepts associated with this product. You can find more detailed information on the subjects covered here by following the links to a set of tutorials and samples that complement this product.

XML Data Compare Features

Two input data files are used for an XML Data Compare comparison, referred to here as 'A' and 'B' files. Whilst it is often the case that 'B' is a modification of 'A', it is also possible that both inputs are derived independently from a common source. Using this terminology, a user-oriented set of high-level features is outlined below:

• Find all the differences between any two XML files ('A' and 'B').

• Use a configuration file with simple XPaths to customise features to fit your data

• Text Splitting for differences on a word-by-word basis.

• Attribute value splitting for differences where detailed comparison is needed.

• Ignore changes to specified elements and attributes.

• Ignore small differences in numeric values.

• Ignore the order of specific sets of elements.

• Ignore non-significant changes to white space characters.

• Display change information in either XML or HTML form, using a standard web browser.

• Report changes only or changes+unchanged data.

• Handle large files without performance degradation.

• A diagnostics mode tests XPaths in the configuration file, this is on by default.

Running a Comparison

XML Data Compare is a Java application that provides comparison functionality through a simple REST API. The XML Data Compare REST service runs locally on your own hardware. Comparisons are run on the XML Data Compare server by making REST API calls through a client application that may be remote from the the server. The REST API allows you to integrate XML Data comparison functionality into your own solutions in a flexible platform-independent way.

The REST User Guide provides details on using the REST API directly using HTTP method calls from an HTTP test environment or, alternatively, running comparisons through a supplied sample client application that provides a command-line interface (CLI).

Customising a Comparison Using a Configuration File

The XML Data Compare REST API takes three inputs:  the data files to be compared, A and B, together with a configuration file that specifies in some detail how the comparison should be done. The configuration file employs XPath expressions to specify the location of content in the data files that requires specific processing. For more details, please visit  Basics: Configuration File and  Configuration File Schema Guide.

Samples

The configuration features of XML Data Compare are explained in detail through a set of samples; each sample demonstrates a different feature and includes a configuration file and sample input XML data files.  The file resources used for each of the samples can be downloaded from our Bitbucket repository. 

Output Formats

Direct XML Data Compare Output

The direct output from XML Data Compare is the 'Delta', this is the base XML output. By default the Delta includes all content from both input files, including unchanged content, but there's also an option for a 'patch' output where only the changes are included. Other output format options are also possible, starting with the side-by-side folding report and described in section 6.2, these are essentially transforms of the original Delta. The specification for deltaV2 format is available here.

Sample Delta:

Supplementary Output Formats

This section describes alternative output formats available with XML Data Compare. These are set within the configuration file.  Initially only the HTML5 side-by-side difference report is available.

HTML Side-by-Side Difference Report

This is a JavaScript-dependent HTML view that presents the comparison result of the raw XML of the input file versions rendered alongside each other. The user-interface provides up/down buttons on a toolbar allowing the end-user to highlight each change.

Feedback

We are always keen to improve our products - please contact us if you have any comments or suggestions while working with XML Data Compare. We hope you enjoy it!

The DeltaXML Team.

Licensing and Legal Notices

The DeltaXML software is licensed under the terms described in the file Licence.html. The software also includes components developed by others, the redistribution and copyright terms, including necessary notices are described in legal-notices.html