Skip to content

Command line client

Philip Helger edited this page Nov 16, 2026 · 3 revisions

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.

Download and start

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.

Exit codes

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

Docker

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.

Building the image

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.

validate

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

convert

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

preprocess

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

streamability

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.

check

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.

Clone this wiki locally