ph-schematron

ph-schematron is a Java library that validates XML documents via ISO Schematron. It is licensed under Apache 2.0 license.

Schematron is now also on GitHub: https://github.com/Schematron It offers several different possibilities to perform this task where each solution offers its own advantages and disadvantages that are outlined below in more detail. ph-schematron only supports ISO Schematron and no other Schematron version. The most common way is to convert the source Schematron file to an XSLT script and apply this XSLT on the XML document to be validated. Alternatively ph-schematron offers a native implementation for the Schematron XPath binding which offers superior performance over the XSLT approach but can only be used, if the Schematron rules consist purely of XPath expressions and don't contain any XSLT.

Continue reading the full documentation at http://phax.github.io/ph-schematron/.

Usage with Maven

The dependency for ph-schematron looks like this:

<dependency>
  <groupId>com.helger</groupId>
  <artifactId>ph-schematron</artifactId>
  <version>5.6.0</version>
</dependency>

It transitively contains ph-commons, SLF4J and Saxon HE.

Maven plugin to convert Schematron to XSLT at build time

The Maven plugin ph-sch2xslt-maven-plugin is deprecated since v5.0.9 - the goal was integrated into ph-schematron-maven-plugin

Maven plugin to convert Schematron (SCH) to XSLT at compile time using ph-schematron as the converter.

The conversion of Schematron to XSLT is quite costly. That’s why this Maven plugin that does the conversion at build time.

By default the plugin is run in the Maven lifecycle phase generate-resources. The basic configuration of the plugin in the pom.xml looks like this (inside the <build>/<plugins> element).

Starting from version 5.0.9:

<plugin>
  <groupId>com.helger.maven</groupId>
  <artifactId>ph-schematron-maven-plugin</artifactId>
  <version>5.6.0</version>
  <executions>
    <execution>
      <goals>
        <goal>convert</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Up to and including version 5.0.8:

<plugin>
  <groupId>com.helger.maven</groupId>
  <artifactId>ph-sch2xslt-maven-plugin</artifactId>
  <version>5.0.8</version>
  <executions>
    <execution>
      <goals>
        <goal>convert</goal>
      </goals>
    </execution>
  </executions>
</plugin>

The possible configuration parameters are:

<configuration>
  ...
  <parameters> 
    <allow-foreign>true</allow-foreign>
    <anything>else</anything>
  </parameters>    
  ...
</configuration>

Maven plugin to validate XML instances against Schematron rules

Maven plugin to validate XML files against convert Schematron (SCH) at compile time using ph-schematron as the validator.

This plugin was introduced in version 4.2.0.

By default the plugin is run in the Maven lifecycle phase process-resources. The basic configuration of the plugin in the pom.xml looks like this (inside the <build>/<plugins> element):

<plugin>
  <groupId>com.helger.maven</groupId>
  <artifactId>ph-schematron-maven-plugin</artifactId>
  <version>5.6.0</version>
  <executions>
    <execution>
      <goals>
        <goal>validate</goal>
      </goals>
    </execution>
  </executions>
</plugin>

The possible configuration parameters are:

Maven plugin to preprocess Schematron files

Maven plugin to preprocess a Schematron file and write the resulting file to disk.

This plugin was introduced in version 5.0.9.

By default the plugin is run in the Maven lifecycle phase generate-resources. The basic configuration of the plugin in the pom.xml looks like this (inside the <build>/<plugins> element):

<plugin>
  <groupId>com.helger.maven</groupId>
  <artifactId>ph-schematron-maven-plugin</artifactId>
  <version>5.6.0</version>
  <executions>
    <execution>
      <goals>
        <goal>preprocess</goal>
      </goals>
    </execution>
  </executions>
</plugin>

The possible configuration parameters are:

ph-schematron-validator

This submodule is a Java library. It is a validator for Schematron definitions based on RelaxNG definition.

Usage with Maven

Add the following to your pom.xml to use this artifact:

<dependency>
  <groupId>com.helger</groupId>
  <artifactId>ph-schematron-validator</artifactId>
  <version>5.6.0</version>
</dependency>

Ant tasks

Since ph-schematron 4.3.0 there is an Apache Ant task that enables you to validate XML files against Schematron rules. As I'm not an Ant expert please forgive me if some of the explanations are not 100% accurate. ph-schematron 5.0.0 adds a new task for preprocessing Schematron files.

Validate documents with Schematron (since 4.3.0)

Declare the task

There is currently only one task:

<taskdef name="schematron" classname="com.helger.schematron.ant.Schematron" />

For this Ant Task to be available you need to include the ph-schematron-ant-task "JAR with dependencies" in your classpath. Alternatively you can use the classpath attribute to reference a classpath that is defined internally in the build script.

A compiled version of the "JAR with dependencies" is available at the Maven Central Repository.

Execute task

The validation itself looks like this:

  <target name="validate">
...
    <schematron schematronFile="sample_schematron.sch" expectSuccess="true">
      <fileset dir="xml">
        <include name="*.xml" />
        <exclude name="err*.xml" />
      </fileset>
    </schematron>
...
  </target>

Basically you declare the Schematron file (relative to the project's base directory), define whether you expect a successful validation or failures, and finally you name the XML files to be validated (as resource collections - e.g. Filesets).

The schematron element allows for the following attributes:

The following child elements are allowed:

Additionally you can use an XMLCatalog that acts as an Entity and URI resolver both for the Schematron and the XML files to be validated! See https://ant.apache.org/manual/Types/xmlcatalog.html for details on the XML catalog. Here is an example that shows how to use an inline XML catalog:

  <target name="validate">
    <schematron schematronFile="../sch/test.sch" 
                expectSuccess="true"
                schematronProcessingEngine="pure">
      <fileset dir=".">
        <include name="test.xml" />
      </fileset>
      <xmlcatalog>
        <dtd publicId="-//bla//DTD XML test//EN" location="../dtd/test.dtd"/>
      </xmlcatalog>
      <errorRole role="fatal" />
      <parameter name="allow-foreign" value="true" />
    </schematron>
  </target>

Preprocess a Schematron file (since 5.0.0)

Declare the task

There is currently only one task:

<taskdef name="schematron-preprocess" classname="com.helger.schematron.ant.SchematronPreprocess" />

For this Ant Task to be available you need to include the ph-schematron-ant-task "JAR with dependencies" in your classpath. Alternatively you can use the classpath attribute to reference a classpath that is defined internally in the build script.

Execute task

The validation itself looks like this:

  <target name="validate">
...
    <schematron-preprocess srcFile="src.sch" dstFile="dst.sch" />
...
  </target>

Basically you define source and destination Schematron files and that's it. Additionally you can define a few settings controlling the output.

The schematron element allows for the following attributes:

News and noteworthy


My personal Coding Styleguide | On Twitter: @philiphelger | Kindly supported by YourKit Java Profiler