Basics: Configuration File

Configuration File Purpose

The configuration file is used to specify how the comparison is required to behave for specific elements or attributes. 

Within elements, it is possible to:

• ignore changes,

• specify how a list of items is matched,

• allow numeric values to have a tolerance,

• normalize whitespace and compare whole blocks or single words. 

The schema for the configuration file is defined using an XML Schema (XSD), the XSD file is included in the product distribution resources and it is documented here.

The Empty Configuration File

When you create a config file, it has to be designed for a particular pair of data files.  It is recommended therefore that the name of the config file connects it to the data files.  The config file should always use the config.xsd file provided with XML Data Compare to ensure validity.

You may like to start with an empty configuration file and examine the results obtained before deciding what to add. 

Empty Configuration File

<dcf:configuration 
  id="config1" 
  version="1.0" 
  xmlns:dcf="com.deltaxml.data.config">
</dcf:configuration>

Editing the Configuration File

XSD Schema association

To help ensure that you create a valid configuration file, it is recommended that you use an XML editor that supports XSD validation and associate the file with the configuration file XSD. The XSD association is made using the xsi:schemaLocation attribute with a URI value that links to the configuration XSD file config.xsd, included in the distribution's resources directory. For example:

<?xml version="1.0" encoding="UTF-8"?>
<dcf:configuration 
  xmlns:dcf="com.deltaxml.data.config"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="com.deltaxml.data.config config.xsd"
  version="1.0"
  id="abcd"
  >
  ...
</dcf:configuration>

Note that in the above example, the configuration file elements use the 'dcf' prefix that is bound to the com.deltaxml.data.config namespace. The namespace is therefore also included as the first part of the xsi:schemaLocation value.

With this XSD association in your configuration file, your XML editor should provide auto-completion and context-specific help documentation as you type.

Writing XPath expressions

With the exception of default feature settings, all configuration feature settings must have a dcf:location element that identifies the elements and/or attributes for which the feature should be applied.

Each dcf:location element has a name attribute that must have a unique value. This name attribute makes the configuration more readable, and helps identify the location of an XPath problem.

A dcf:location element also has an xpath attribute. The value for this attribute is an XPath expression as specified in the XPath 3.1 specification. The XPath expression should return zero or more attribute and/or element nodes when evaluated against the input XML. Any returned nodes provide the context for the feature that is specified as a child element of the dcf:location element.

XML Namespaces

It is quite likely that your input XML elements (and possible attributes) have a specified namespace. If they are in a namespace that is not the default namespace, element or attribute names have a prefix followed by ':'. An xmlns attribute binds prefixes or the default namespace (which has no prefix) to a specific namespace URI. For example, in a Maven pom.xml file, we find:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  ...
</project>

In the example above, the xmlns attribute (line 1) declares http://maven.apache.org/POM/4.0.0 as the default namespace (there is no prefix). The xmlns:xsi attribute (line 2) binds the xsi prefix with the http://www.w3.org/2001/XMLSchema-instance namespace URI. The modelVersion element, a child of the project element, has no prefix; it therefore inherits the default namespace  http://maven.apache.org/POM/4.0.0 declared on its parent element.

If an XPath expression in a configuration file is to return the modelVersion element it must specify the namespaces in all node-tests within the XPath (or explicitly specify any namespace using '*:' as a prefix in the node-test). XPath node-tests are evaluated using a namespace-context, specified in the dcf:xpath-namespaces element. This element is used to declare the default namespace and/or a set of namespace declarations associating a given prefix with a namespace URI. See the example in the next section.

XPath using the Default Namespace

In this case, to use the XPath:

/project/modelVersion

We must specify in the configuration file what the default namespace is, as follows:

<dcf:configuration 
  xmlns:dcf="com.deltaxml.data.config"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
  xsi:schemaLocation="com.deltaxml.data.config xdc-config.xsd"
  version="1.0"
  id="abcd"
  >
  
  <dcf:xpath-namespaces>
    <dcf:default-namespace uri="http://maven.apache.org/POM/4.0.0"/>
  </dcf:xpath-namespaces>
  
  <dcf:location name="IgnoreModelVersion" xpath="/project/modelVersion">
    <dcf:ignore-changes use="BA"/>
  </dcf:location>

</dcf:configuration>

In the example above, there is a dcf:xpath-namespaces element with a child-element dcf:default-namespace specifying http://maven.apache.org/POM/4.0.0 as the default namespace. The XPath /project/modelVersion will therefore return the mavenProject element.

XPath using a Non-Default Namespace

It may be desirable or necessary to use XPaths with a non-default namespace, for example, if the input XML has more than one namespace. In this case, a prefix is used in node-tests included in the XPath:

/mvn:project/mvn:modelVersion

To use the above expression in a configuration file, we must declare the namespace-URI binding for the 'mvn' prefix used in the XPath as follows:

<dcf:configuration 
  xmlns:dcf="com.deltaxml.data.config"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="com.deltaxml.data.config xdc-config.xsd"
  version="1.0"
  id="abcd"
  >
  
  <dcf:xpath-namespaces>
    <dcf:namespace prefix="mvn" uri="http://maven.apache.org/POM/4.0.0"/>
  </dcf:xpath-namespaces>
  
  <dcf:location name="IgnoreModelVersion" xpath="/mvn:project/mvn:modelVersion">
    <dcf:ignore-changes use="BA"/>
  </dcf:location>

</dcf:configuration>

In the configuration file above, the dcf:namespace element declares the prefix and namespace-uri binding. A dcf:namespace element is required for each prefix used in XPaths in the configuration file.

Attributes and XML Namespaces

The above examples use element node-tests. When using an attribute node-test, for example with /element/@attribute the absence of a prefix in '@attribute' means the attribute is not in any namespace (i.e. it is in the 'null' namespace) even with the default namespace declared. This is normally the desired behaviour because attributes in XML are always in the null namespace unless they have a prefix.

XPath Restrictions

To improve comparison performance, XPath expressions in configuration files are often processed internally in the 'match' attribute of a generated XSLT template.

As a consequence of this, a number of restrictions apply, these are summarised here:

An XPath 3.1 compatible 'match' pattern must be used. The syntax used for a pattern is defined here: https://www.w3.org/TR/xslt-30/#pattern-syntax

Some notable features:

• The ',' comma XPath separator operator can only be used in sub-expressions (the union '|' operator can be used instead in many cases)

• The context item for the evaluation of the XPath is the XML document node (i.e. not the root element)

• The main XPath expression should start with a /

Diagnostic Mode and XPath Errors

XML Data Compare runs comparisons with a 'Diagnostics Mode' set on by default. This mode allow for errors in XPath expressions to be reported in more detail, helping you identify the location of the problem in the configuration file. In this mode, each XPath expression is evaluated separately first, this may result in it taking longer to perform a comparison on large XML input files. The diagnostics mode can be switched off via the XML Data Compare REST API. The sample command-line interface client shows how this is done.

More Configuration with Samples

You will know your data structure well and be aware of the issues that can happen in a comparison.

The locations where you want to change the default action of the comparison are specified by XPath expressions.  Edit the configuration file to give the settings required and the locations as XPath expressions.  Experiment in an XML editor such as oXygen to confirm that your Xpath expressions are correct.