mirror of
https://github.com/itplr-kosit/validator.git
synced 2026-07-25 08:05:48 +00:00
ba93207b77
scripts/validate.sh is the engine behind both platforms: download the released standalone jar and the validation configuration (SHA-256-verified when pinned), validate each document, print PASS/FAIL with the failing rule ids and fail on any rejection. The GitHub Action (action.yml) maps its inputs onto the script's environment; the GitLab template fetches the same script from this repository at KOSIT_SCRIPT_REF and drives it with the same variables, so both platforms run identical logic. With Docker available the action executes each validation sealed (the "sealed" input, default "auto"): inside an eclipse-temurin:21-jre container without network access, a read-only root and no capabilities, with only the jar, the configuration and a scratch directory mounted; downloads always happen outside the container, so the validator itself never touches the network, and the host JVM setup is skipped entirely for "sealed: always". The image tag pins the Java 21 JRE contract and floats the patch level: the released jars are the checksummed artifacts, the runtime is a security-patch channel; an "image" input (KOSIT_IMAGE on GitLab) accepts a digest-pinned reference for stricter policies. The GitLab job image is the same runtime, giving both platforms an identical execution environment, and a devcontainer provides the matching Maven and Java setup for development. The action self-test validates a conformant XRechnung reference instance and asserts a corrupted one is rejected, exercising the sealed path through the empty-input fallback and an explicit image override, plus the host path.
179 lines
No EOL
8.2 KiB
Markdown
179 lines
No EOL
8.2 KiB
Markdown
# KoSIT Validator
|
|
|
|
[](https://central.sonatype.com/artifact/org.kosit/validator)
|
|
[](https://www.apache.org/licenses/LICENSE-2.0)
|
|
|
|
|
|
## 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
|
|
1. validate the XML file (using schema and schematron rules)
|
|
1. generate a custom report / extract custom data from the XML file
|
|
1. compute an acceptance status (according the supplied schema and rules)
|
|
|
|
The Validator depends on self defined [scenarios](docs/configurations.md) in order to fully configure the whole process.
|
|
It always creates a [validation report in XML](docs/configurations.md#validators-report). The actual content of the report can also be controlled by the scenario.
|
|
|
|
See [architecture](docs/architecture.md) 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](docs/configurations.md) 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](https://xeinkauf.de/xrechnung/):
|
|
* Source code is available on [GitHub](https://github.com/itplr-kosit/validator-configuration-xrechnung)
|
|
* [Releases](https://github.com/itplr-kosit/validator-configuration-xrechnung/releases) can also be downloaded
|
|
* Validation Configuration for [Peppol BIS Billing](https://docs.peppol.eu/poacc/billing/3.0/):
|
|
* Source code is available on [GitHub](https://github.com/itplr-kosit/validator-configuration-bis)
|
|
* [Releases](https://github.com/itplr-kosit/validator-configuration-bis/releases) can also be downloaded
|
|
* Validation Configuration for [XGewerbeanzeige](https://xgewerbeanzeige.de/)
|
|
* Source code is available on [GitHub](https://github.com/itplr-kosit/validator-configuration-xgewerbeanzeige)
|
|
* [Releases](https://github.com/itplr-kosit/validator-configuration-xgewerbeanzeige/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:
|
|
|
|
```shell
|
|
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:
|
|
|
|
```shell
|
|
java -jar validator-<version>-standalone.jar --help
|
|
```
|
|
|
|
A concrete example with a specific Validator configuration can be found on
|
|
[validator-configuration-bis](https://github.com/itplr-kosit/validator-configuration-bis)
|
|
|
|
The [CLI documentation](./docs/cli.md) 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:
|
|
|
|
```java
|
|
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](./docs/api.md) 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.
|
|
|
|
```shell
|
|
java -jar validator-<version>-standalone.jar -s <scenario-config-file> -D
|
|
```
|
|
|
|
|
|
The [daemon documentation](./docs/daemon.md) 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:
|
|
|
|
```yaml
|
|
- 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 and no capabilities; 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`](./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
|
|
1. **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)
|
|
1. **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)
|
|
|
|
```xml
|
|
<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:
|
|
|
|
```xml
|
|
<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](https://github.com/xproc/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](https://github.com/itplr-kosit/validator/graphs/contributors).
|
|
|
|
## License
|
|
|
|
The Validator is licensed under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0). |