Repository navigation
Command line client
Since v11.0.0 ph-schematron has a command line client (module ph-schematron-cli, #188).
It offers the functionality of the Maven plugin and the ANT tasks and shares their implementation (module ph-schematron-engine-factory), so all three behave the same way.
The executable JAR with all dependencies is ph-schematron-cli-x.y.z-shaded.jar (replace x.y.z with the version number), available at the Maven Central Repository.
A local build creates the same file in ph-schematron-cli/target/.
It requires Java 21 or later and contains both XSLT processors, Saxon and phoxtrot (see XSLT processors).
java -jar ph-schematron-cli-x.y.z-shaded.jar <command> [options]
| Command | Purpose | Same as |
|---|---|---|
validate |
Validate XML files against a Schematron | Maven goal validate, Ant task schematron
|
convert |
Convert Schematron files to XSLT files | Maven goal convert, Ant task schematron-convert
|
preprocess |
Write a preprocessed Schematron | Maven goal preprocess, Ant task schematron-preprocess
|
streamability |
Report the streamability of a Schematron (see Streamability) | Maven goal streamability, Ant task schematron-streamability
|
check |
Validate Schematron files against the RELAX NG schema of ISO Schematron (2006) | - |
help |
Show the help of a command | - |
--help (or -h) shows the options of every command, --version (or -V) the version.
All commands have the options -v / --verbose (also debug messages and stack traces) and -q / --quiet (only warnings and errors).
Results and info messages go to the standard output, warnings and errors to the error output.
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | An expectation was not met: an XML file failed the validation, a Schematron needs more than --max-class, a Schematron is not valid (check) |
| 2 | Invalid command line, e.g. an unknown option, engine or file |
| 3 | Invalid Schematron or a technical error, e.g. an XML file that cannot be read |
The command line client is also available as Docker image phelger/schematron, with the tags x.y.z and latest, for linux/amd64 and linux/arm64.
It runs the shaded JAR on Java 25; the arguments of docker run after the image name are passed to the client.
The working directory in the container is /data, so mount the directory with the files there and use relative paths:
docker run --rm -v "$PWD:/data" phelger/schematron:x.y.z validate -s rules.sch xml/
On Linux the files written by the client (e.g. with --svrl-dir or convert) belong to root, unless the container runs with your user: add --user "$(id -u):$(id -g)".
Files outside the mounted directory are not visible in the container, and the exit codes are the same as above.
The Dockerfile is in the module ph-schematron-cli and copies the shaded JAR from target/, so build the module first.
The image is published manually with the script docker/build-all.sh: set version in it to the released version, then run
mvn install
cd docker
./build-all.sh
The script fails unless ph-schematron-cli/target/ contains exactly the shaded JAR of that version.
It builds both platforms with docker buildx and pushes the tags x.y.z and latest.
java -jar ph-schematron-cli-x.y.z-shaded.jar validate -s rules.sch xml/ --expect-invalid xml-invalid/
The arguments are XML files or directories that must be valid; --expect-invalid names files or directories that must contain at least one Schematron error.
In directories, all files matching --include (default **/*.xml) and not matching --exclude are validated, recursively.
Only failed asserts and successful reports with level error or fatal error decide whether a file is valid (see Maven plugin for how the level is determined).
| Option | Meaning |
|---|---|
-s, --schematron FILE
|
The Schematron file (an XSLT file for the engine xslt). Required |
-e, --engine ID
|
pure-xpath, pure-xslt, iso-schematron, schxslt, schxslt2 or xslt, with the aliases of the engines. Default iso-schematron
|
-x, --xslt-processor ID
|
saxon or phoxtrot, for the engines iso-schematron, schxslt, schxslt2 and xslt. Default saxon
|
--phase NAME |
The phase to use. Default: the defaultPhase of the Schematron |
--language CODE |
The language code of the engines iso-schematron, schxslt and schxslt2 (cs, de, en, fr, nl) |
-P, --param NAME=VALUE
|
A custom XSLT parameter, e.g. -P allow-foreign=true. Repeatable |
--force-cache-result |
Force the caching of the SCH to XSLT conversion |
--lenient |
Accept deprecated Schematron namespace URIs (engine pure-xpath only) |
--catalog FILE |
An OASIS XML catalog file for entities and URIs. External DTDs and entities of the XML files are loaded only via the catalogs; a reference that is not in a catalog makes the file fail. Repeatable |
--include GLOB, --exclude GLOB
|
The files of directory arguments to validate or skip, e.g. **/*.xml. Repeatable |
--expect-invalid PATH |
An XML file or directory that must contain at least one Schematron error. Repeatable |
--svrl-dir DIR |
Write the SVRL of each XML file into this directory (relative path plus .svrl) |
--ignore-warnings |
Neither log nor count warnings and information |
--error-role ROLE |
A value of role, flag or severity that is treated as error. Repeatable |
--fail-on-error |
Fail a file with a Schematron error, also with --expect-invalid
|
--fail-on-warning, --fail-on-info
|
Fail a file with a Schematron warning or information |
--fail-fast |
Stop at the first file that fails. By default all files are validated |
java -jar ph-schematron-cli-x.y.z-shaded.jar convert -o xslt/ schematron/
java -jar ph-schematron-cli-x.y.z-shaded.jar convert -o - rules.sch > rules.xslt
The arguments are Schematron files or directories; in directories all files matching --pattern (default **/*.sch) are converted, recursively.
The XSLT files are written to the directory given with -o / --out, with the relative path of the Schematron file.
-o - writes the XSLT of a single Schematron file to the standard output.
The engine options -e, -x, --phase, --language, -P and --force-cache-result are the same as for validate; the engine must be iso-schematron, schxslt, schxslt2 or pure-xslt.
| Option | Meaning |
|---|---|
-o, --out DIR
|
The directory for the XSLT files, or - for the standard output. Required |
--pattern GLOB |
The Schematron files of directory arguments. Default **/*.sch
|
--xslt-extension EXT |
The file extension of the XSLT files. Default .xslt
|
--no-overwrite |
Leave existing XSLT files untouched |
--xslt-header TEXT |
A text added as XML comment to each XSLT file |
--show-progress |
Log a message every 5 seconds while a conversion takes longer |
--continue-on-error |
Continue with the next Schematron file after an error |
java -jar ph-schematron-cli-x.y.z-shaded.jar preprocess -s rules.sch -o rules-preprocessed.sch
Preprocesses the Schematron like the Maven goal preprocess: includes, abstract patterns and abstract rules are resolved, with the query binding of the Schematron.
Without -o the result is written to the standard output.
| Option | Meaning |
|---|---|
-s, --schematron FILE
|
The Schematron file. Required |
-o, --out FILE
|
The file to write. Default: the standard output |
--keep-titles, --keep-diagnostics
|
Keep the title or diagnostic elements |
--keep-reports |
Keep the report elements instead of converting them to assert elements |
--keep-empty-patterns |
Keep pattern elements without a rule |
--sch-header TEXT |
A text added as XML comment |
--no-overwrite |
Leave an existing output file untouched |
java -jar ph-schematron-cli-x.y.z-shaded.jar streamability --max-class burst rules.sch
Reports per rule whether the Schematron can be validated while streaming (see Streamability).
With --max-class (motionless, burst or non-local) a Schematron that needs more fails with exit code 1.
java -jar ph-schematron-cli-x.y.z-shaded.jar check rules.sch
Validates Schematron files against the RELAX NG Compact schema of ISO Schematron (ISO/IEC 19757-3:2006), using ph-schematron-validator.
This only checks the structure of the Schematron, not its XPath expressions; use validate for that.
On Twitter: Follow @philiphelger
Donation link: https://paypal.me/PhilipHelger
It is appreciated if you star the GitHub project if you like it.