KoSIT Validator

Introduction

The Validator is an XML validation engine to validate and process XML files in various formats. It basically does the following in order:

1. identify actual XML format
2. validate the XML file (using schema and schematron rules)
3. generate a custom report / extract custom data from the XML file
4. compute an acceptance status (according the supplied schema and rules)

The Validator depends on self defined scenarios in order to fully configure the whole process. It always creates a validation report in XML. The actual content of the report can also be controlled by the scenario.

See architecture for information about the whole validation process.

Validation configurations

The Validator is just an engine and does not know anything about XML documents and has no own validation rules. Validation rules and details are defined in validation scenarios which are used to fully configure the validation process. All configurations are self-contained modules which are deployed and developed on their own.

Example validation configurations

Here are some public validation configurations:

• Validation Configuration for XRechnung:
  • Source code is available on GitHub
  • Releases can also be downloaded
• Validation Configuration for Peppol BIS Billing:
  • Source code is available on GitHub
  • Releases can also be downloaded
• Validation Configuration for XGewerbeanzeige
  • Source code is available on GitHub
  • Releases can also be downloaded

Usage

The Validator can be used in three different ways:

• as standalone application running from the CLI
• as library embedded within a custom application
• as a daemon providing an http interface

Standalone Command Line Interface (CLI)

Important hint: since v1.5.1 the filename has been changed from validationtool-* to validator-*

The general way using the CLI is:

java -jar validator-<version>-standalone.jar -s <scenario-config-file> [-r <repository-path>]
[OPTIONS] [FILE] [FILE] [FILE] ...

The help option displays further CLI options to customize the process:

java -jar validator-<version>-standalone.jar --help

A concrete example with a specific Validator configuration can be found on validator-configuration-bis

The CLI documentation shows further configuration options.

Application User Interface (API / embedded usage)

The Validator can also be used in own Java Applications via the API. An example use of the API as follows:

URL scenarios = this.getClass().getClassLoader().getResource("scenarios.xml");
Configuration config = Configuration.load(scenarios.toURI()).build(ProcessorProvider.getProcessor());
Check validator = new DefaultCheck(config);

Input document = InputFactory.read(testDocument);
Result report = validator.checkInput(document);

// examine the result here

The API documentation shows further configuration options.

Note: With Java 11+, you need to include a dependency to org.glassfish.jaxb:jaxb-runtime in your project explicitly, as that dependency is marked optional in this project and will thus not be resolved transitively.

Daemon-Mode

You can also start the validator as a HTTP-Server. Just start it in Daemon-Mode with the -D option.

java -jar  validator-<version>-standalone.jar  -s <scenario-config-file> -D

The daemon documentation shows more usage details and further configuration options.

Continuous Integration

The repository ships a GitHub Action and a GitLab CI template so documents can be validated as part of a pipeline.

Validate a directory of XML documents against the current XRechnung configuration with the GitHub Action:

- uses: itplr-kosit/validator@main
  with:
    version: "1.6.2"
    configuration: "https://github.com/itplr-kosit/validator-configuration-xrechnung/releases/download/v2026-01-31/xrechnung-3.0.2-validator-configuration-2026-01-31.zip"
    files: invoices/

The action downloads the released standalone jar, runs every document and fails the job if any document is rejected, printing the failing rule ids. The optional checksum and configuration-checksum inputs verify the downloads against a SHA-256 pin. The reports are written to report-dir (default validator-reports), and the accepted/rejected counts are exposed as outputs.

When Docker is available on the runner the action executes the validator inside an eclipse-temurin:21-jre container without network access, a read-only root, no capabilities and no privilege escalation; the document and the configuration are mounted read-only, only the report directory is writable, and downloads always happen outside the container, so the validator itself never touches the network. The sealed input controls this (auto default, always, never), and the image input replaces the default image — the floating tag receives Java security patches automatically, while a digest-pinned reference can be passed for a stricter supply-chain policy.

On GitLab, include gitlab/validator.gitlab-ci.yml and extend the .kosit-validate job template; its variables mirror the action inputs and its job image is the same pinned runtime the sealed action uses, so both platforms execute the validator in an identical environment.

Packages

The Validator distribution contains the following artifacts:

1. validator-<version>.jar: Java library for embedded use within an application
2. validator-<version>-standalone.jar: Uber-JAR for standalone usage containing all dependencies in one jar file. This file comes with JAXB embedded and can be used with Java >= 11)
3. libs/: directory containing all (incl. optional) dependencies of the validator

Installation

Download from the following sources is possible:

• GitHub releases: https://github.com/itplr-kosit/validator/releases
  • This release contains a ZIP file with all the different JAR variants
• Maven Central with the below coordinates (replace x.y.z with the actual version to use)

<dependency>
    <groupId>org.kosit</groupId>
    <artifactId>validator</artifactId>
    <version>x.y.z</version>
</dependency>

To use the standalone version with Maven coordinates, add the respective classifier:

<dependency>
    <groupId>org.kosit</groupId>
    <artifactId>validator</artifactId>
    <version>x.y.z</version>
    <classifier>standalone</classifier>
</dependency>

Roadmap

This section describes the next steps planned in the Validator development.

• Version 1.5.x is frozen - no maintainance, no support
• Version 1.6.x - no feature development, but maintainance and best-effort support
• Develop version 2.0.0 which will include major API incompatibilities - Winter 2025
  • Rework scenarios.xml
  • Rework report output engine
  • Change the output type to XVRL-based document types → this implies that existing XSL templates need to be updated
  • Consider multi Schematron engine support
  • Extract the daemon mode into its own submodule
  • Consider extracting the CLI into its own submodule
• The release of version 2.0.0 implies a feature-freeze for version 1.6

Authors & Acknowledgements

We are thankful to numerous third-party contributors.

License

The Validator is licensed under the Apache 2.0 license.