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:

• File schematronFile - The Schematron file to be used for validation
• String schematronProcessingEngine - The internal engine to be used. Must be one of pure, schematron or xslt. The default is schematron. In v5.0.0 sch was added as an alias for schematron.
• File svrlDirectory - An optional directory where the SVRL files should be written to.
• String phaseName - The optional Schematron phase to be used. Note: this is only available when using the processing engine pure or schematron. For engine xslt this is not available because this was defined when the XSLT was created.
• String languageCode - The optional language code to be used. Note: this is only available when using the processing engine schematron. For engine xslt this is not available because this was defined when the XSLT was created. Default is English (en). Supported language codes are: cs, de, en, fr, nl.
• boolean expectSuccess - true to expect successful validation, false to expect validation errors. If the expectation is incorrect, the build will fail.
• boolean failOnError (since v5.0.0) - true to break the build if an error occurred, false to continue with the following tasks on error. The default value is true.
• boolean failOnValidationError (since v5.0.11) - true to break the build, if any Schematron error is reported. This setting has lower precedence than expectSuccess. The default value is false.
• boolean failOnValidationWarn (since v5.0.11) - true to break the build, if any Schematron warning is reported. This setting has lower precedence than expectSuccess. The default value is false.
• boolean failOnValidationInfo (since v5.0.11) - true to break the build, if any Schematron information is reported. This setting has lower precedence than expectSuccess. The default value is false.

The following child elements are allowed:

• <errorRole> (since v5.0.2)
  • The usage of the element is optional.
  • The role attribute allows to define values of role and flag attributes in Schematrons that are considered as errors.
  • If this element is combined with the failOnError attribute you can break the build if an assertion with the respective role or flag fails.
• <parameter> (since v5.0.6)
  • The usage of the element is optional.
  • The element is only interpreted for the processing engines xslt and sch.
  • The attribute 'name' defines the custom attribute name.
  • The attribute 'value' defines the custom attribute value. If the value is omitted, an empty String is passed instead.

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:

• File srcFile - The source Schematron file to be preprocessed. This parameter is required.
• File dstFile - The destination file in which the preprocessed content should be written. This parameter is required.
• boolean keepTitles - true to keep <title>-elements, false to delete them. Default is false.
• boolean keepDiagnostics - true to keep <diagnostic>-elements, false to delete them. Default is false.
• boolean keepReports - true to keep <report>-elements, false to change them to <assert>-elements. Default is false.
• boolean keepEmptyPatterns - true to keep <pattern>-elements without rules, false to delete them. Default is true.
• boolean failOnError - true to break the build if an error occurred, false to continue with the following tasks on error.