demo/validator
1
0
Fork 0
mirror of https://github.com/itplr-kosit/validator.git synced 2026-05-25 16:55:39 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch '151-release-docs' into 'release/1.5.x'

Browse source 
Release documentation update

See merge request kosit/validator!73
This commit is contained in:
Renzo Kottmann 2025-08-29 10:15:40 +02:00
commit 02d12b614e
3 changed files with 50 additions and 42 deletions
Download patch file Download diff file Expand all files Collapse all files

38
README.md
View file

@ -1,4 +1,5 @@
# KoSIT Validator # KoSIT Validator
- [Introduction](#introduction) - [Introduction](#introduction)
- [Validation Configurations](#validation-configurations) - [Validation Configurations](#validation-configurations)
* [Third Party Validation Configurations](#third-party-validation-configurations) * [Third Party Validation Configurations](#third-party-validation-configurations)
@ -9,17 +10,18 @@
- [Packages](#packages) - [Packages](#packages)
## Introduction ## 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 The validator is an XML validation engine to validate and process XML files in various formats. It basically does the following in order:
1. validate the xml file (using schema and schematron rules)
1. generate a custom report / extract custom data from the xml file 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) 1. compute an acceptance status (according the supplied schema and rules)
The validator depends on self defined [scenarios](docs/configurations.md) which are used to fully configure the process. 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 this is controlled by the scenario. 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 actual validation process. See [architecture](docs/architecture.md) for information about the whole validation process.
## Validation configurations ## Validation configurations
@ -30,7 +32,7 @@ All configurations are self-contained modules which are deployed and developed o
### Third party validation configurations ### Third party validation configurations
Currently, there are two public third party validation configurations available. Here are two public third party validation configurations available which might serve as examples:
* Validation Configuration for [XRechnung](http://www.xoev.de/de/xrechnung): * Validation Configuration for [XRechnung](http://www.xoev.de/de/xrechnung):
* Source code is available on [GitHub](https://github.com/itplr-kosit/validator-configuration-xrechnung) * Source code is available on [GitHub](https://github.com/itplr-kosit/validator-configuration-xrechnung)
@ -43,29 +45,31 @@ Currently, there are two public third party validation configurations available.
The validator can be used in three different ways: The validator can be used in three different ways:
* as standalone application running from the cli * as standalone application running from the CLI
* as library embedded within a custom application * as library embedded within a custom application
* as a daemon providing a http interface * as a daemon providing a http interface
### Standalone Command-Line 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: The general way using the CLI is:
```shell ```shell
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file> -r <repository-path> java -jar validator-<version>-standalone.jar -s <scenario-config-file> -r <repository-path>
[OPTIONS] [FILE] [FILE] [FILE] ... [OPTIONS] [FILE] [FILE] [FILE] ...
``` ```
The help option displays further CLI options to customize the process: The help option displays further CLI options to customize the process:
```shell ```shell
java -jar validationtool-<version>-standalone.jar --help java -jar validator-<version>-standalone.jar --help
``` ```
A concrete example with a specific validator configuration can be found on A concrete example with a specific validator configuration can be found on
[GitHub](https://github.com/itplr-kosit/validator-configuration-xrechnung) [GitHub](https://github.com/itplr-kosit/validator-configuration-xrechnung)
The [CLI documentation](./docs/cli.md) shows further configuration options. The [CLI documentation](./docs/cli.md) shows further configuration options.
### Application User Interface (API / embedded usage) ### Application User Interface (API / embedded usage)
@ -93,7 +97,7 @@ will thus not be resolved transitively.
You can also start the validator as a HTTP-Server. Just start it in _Daemon-Mode_ with the `-D` option. You can also start the validator as a HTTP-Server. Just start it in _Daemon-Mode_ with the `-D` option.
```shell ```shell
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file> -D java -jar validator-<version>-standalone.jar -s <scenario-config-file> -D
``` ```
@ -103,7 +107,7 @@ The [daemon documentation](./docs/daemon.md) shows more usage details and furthe
The validator distribution contains the following artifacts: The validator distribution contains the following artifacts:
1. **validationtool-`<version>`.jar**: Java library for embedded use within an application 1. **validator-`<version>`.jar**: Java library for embedded use within an application
1. **validationtool-`<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 8 and Java >= 11) 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 8 and Java >= 11)
1. **validationtool-`<version`>-java8-standalone.jar**: Uber-JAR for standalone usage with Java JDK 8 containing all dependencies in one jar file. This file file *does not* contain JAXB and depends on the bundled version of the JDK. 1. **validator-`<version`>-java8-standalone.jar**: Uber-JAR for standalone usage with Java JDK 8 containing all dependencies in one jar file. This file file *does not* contain JAXB and depends on the bundled version of the JDK.
1. **libs/***: directory containing all (incl. optional) dependencies of the validator 1. **libs/***: directory containing all (incl. optional) dependencies of the validator

46
docs/cli.md
View file

@ -1,27 +1,29 @@
# Validator CLI # Validator Command Line Interface (CLI)
The validator comes with a commandline interface (CLI) which allows validating any number of input xml files. The `validator` comes with a command line interface (CLI) which allows validating any number of input XML files.
**Important hint**: since v1.5.1 the filename has been changed from `validationtool-*` to `validator-*`
The general way using the CLI is: The general way using the CLI is:
```shell ```shell
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file> [OPTIONS] [FILE] [FILE] [FILE] ... java -jar validator-<version>-standalone.jar -s <scenario-config-file> [OPTIONS] [FILE] [FILE] [FILE] ...
``` ```
The validator can also read the xml file from the standard input The validator can also read the XML file from the standard input
```shell script
# via redirection
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file> [OPTIONS] < my-input.xml
# read from pipe
cat my-input.xml | validationtool-<version>-standalone.jar -s <scenario-config-file> [OPTIONS]
```
The help option displays further CLI options to customize the process:
```shell ```shell
java -jar validationtool-<version>-standalone.jar --help # via redirection
java -jar validator-<version>-standalone.jar -s <scenario-config-file> [OPTIONS] < my-input.xml
# read from pipe
cat my-input.xml | validator-<version>-standalone.jar -s <scenario-config-file> [OPTIONS]
```
The help option displays further CLI options:
```shell
java -jar validator-<version>-standalone.jar --help
``` ```
You can also use multiple scenario configurations and multiple repositories with resources for these. The validator either supports You can also use multiple scenario configurations and multiple repositories with resources for these. The validator either supports
@ -29,17 +31,17 @@ supplying the parameters in order or using named configuration. Valid usages are
```shell ```shell
# multiple scenarios, implicit repository # multiple scenarios, implicit repository
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file1> -s <scenario-config-file2> [OPTIONS] [FILE] java -jar validator-<version>-standalone.jar -s <scenario-config-file1> -s <scenario-config-file2> [OPTIONS] [FILE]
# multiple scenarios, single defined repository # multiple scenarios, single defined repository
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file1> -s <scenario-config-file2> -r <path-to-repo> [OPTIONS] [FILE] java -jar validator-<version>-standalone.jar -s <scenario-config-file1> -s <scenario-config-file2> -r <path-to-repo> [OPTIONS] [FILE]
# multiple scenarios, multiple repositories ordered # multiple scenarios, multiple repositories ordered
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file1> -r <path-to-repo1> -s <scenario-config-file2> -r <path-to-repo2> [OPTIONS] [FILE] java -jar validator-<version>-standalone.jar -s <scenario-config-file1> -r <path-to-repo1> -s <scenario-config-file2> -r <path-to-repo2> [OPTIONS] [FILE]
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file1> -s <scenario-config-file2> -r <path-to-repo1> -r <path-to-repo2> [OPTIONS] [FILE] java -jar validator-<version>-standalone.jar -s <scenario-config-file1> -s <scenario-config-file2> -r <path-to-repo1> -r <path-to-repo2> [OPTIONS] [FILE]
# multiple scenarios, multiple repositories (named) # multiple scenarios, multiple repositories (named)
java -jar validationtool-<version>-standalone.jar -s "NAME1=<scenario-config-file1>" -s "NAME2=<scenario-config-file2>" -r "NAME1=<path-to-repo1>" -r "NAME2=<path-to-repo2>" [OPTIONS] [FILE] java -jar validator-<version>-standalone.jar -s "NAME1=<scenario-config-file1>" -s "NAME2=<scenario-config-file2>" -r "NAME1=<path-to-repo1>" -r "NAME2=<path-to-repo2>" [OPTIONS] [FILE]
``` ```
## Special features ## Special features
@ -57,7 +59,7 @@ generated reports. This is mainly useful for scenario developers. Ask KoSIT for
| code | description | | code | description |
|-|-| |-|-|
| 0 | All validated xml files are acceptable according to the scenario configurations | | 0 | All validated xml files are acceptable according to the scenario configurations or application usage was requested |
| positive integer | Number of rejected (e.g. not acceptable) xml files according to the scenario configurations| | positive integer | Number of rejected (e.g. not acceptable) xml files according to the scenario configurations|
| -1 | Parsing error. The commandline arguments specified are incorrect | | -1 | Parsing error. The commandline arguments specified are incorrect |
| -2 | Configuration error. There is an error loading the configuration and/or validation targets | | -2 | Configuration error. There is an error loading the configuration and/or validation targets |

8
docs/daemon.md
View file

@ -8,8 +8,10 @@ and should work with OpenJDK based distributions. Keep this in mind, if you want
To use the validator daemon as is, start the _Daemon-Mode_ with the `-D` option and supply a suitable To use the validator daemon as is, start the _Daemon-Mode_ with the `-D` option and supply a suitable
[validator configuration](configurations.md). [validator configuration](configurations.md).
**Important hint**: since v1.5.1 the filename has been changed from `validationtool-*` to `validator-*`
```shell ```shell
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file> -D java -jar validator-<version>-standalone.jar -s <scenario-config-file> -D
``` ```
Per default the HTTP-Server listens on _localhost_ at Port 8080. Per default the HTTP-Server listens on _localhost_ at Port 8080.
@ -17,7 +19,7 @@ Per default the HTTP-Server listens on _localhost_ at Port 8080.
You can configure the daemon with `-H` for IP Adress and `-P` for port number: You can configure the daemon with `-H` for IP Adress and `-P` for port number:
```shell ```shell
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file> -D -H 192.168.1.x -P 8081 java -jar validator-<version>-standalone.jar -s <scenario-config-file> -D -H 192.168.1.x -P 8081
``` ```
## Customized usage ## Customized usage
@ -135,5 +137,5 @@ The daemon provides a simple GUI when issuing `GET` requests providing the follo
The GUI can be disabled using the API (see above) or via CLI: The GUI can be disabled using the API (see above) or via CLI:
```shell script ```shell script
java -jar validationtool-<version>-standalone.jar -s <scenario-config-file> -D --disable-gui java -jar validator-<version>-standalone.jar -s <scenario-config-file> -D --disable-gui
``` ```