ANT tasks - phax/ph-schematron GitHub Wiki

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.

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.

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. Since v10.0.0 the following engines are supported (canonical id, with the accepted aliases in parentheses):

  • pure-xpath (alias pure) - the pure-Java XPath-only engine.
  • pure-xslt (alias pure-saxon) - the pure-Java engine that generates an XSLT 3.0 stylesheet and runs it via Saxon. Added in v10.0.0.
  • iso-schematron (aliases iso, isoschematron, schematron, sch) - the SCH file is converted to XSLT via the ISO Schematron stylesheet chain and applied from there. This is the default.
  • schxslt (aliases schxslt1, schxslt-xslt2) - the SchXslt v1 engine (XSLT 2). Added to the Ant task in v10.0.0.
  • schxslt2 - the SchXslt v2 engine (XSLT 3). Added to the Ant task in v10.0.0.
  • xslt - apply a pre-built XSLT file directly.

  All engine ids that existed before v10 (pure, schematron, sch, xslt) continue to work as aliases, so existing build scripts need no change. Note: prior to v10.0.0 the Ant task only supported pure, schematron and xslt.

• File svrlDirectory - An optional directory where the SVRL files should be written to.

• String phaseName - The optional Schematron phase to be used. Available for all engines except xslt (for a pre-built xslt the phase was already fixed when the XSLT was created).

• String languageCode - The optional language code to be used. Only used by the XSLT-generating engines iso-schematron, schxslt and schxslt2. It has no effect for the pure-xpath / pure-xslt engines or for a pre-built xslt (there it 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 XSLT-based engines: iso-schematron (sch), schxslt, schxslt2 and xslt. It is ignored by the pure-xpath / pure-xslt engines.
  • 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>

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.

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-preprocess 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.