From 162339d485b09c661d5acfd2fdc6b44ba837ae78 Mon Sep 17 00:00:00 2001 From: Philip Helger Date: Wed, 3 Sep 2025 15:30:37 +0200 Subject: [PATCH 1/6] Added Maven Central badge --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index cf6d9f7..49a3257 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # KoSIT Validator +[![Maven Central](https://img.shields.io/maven-central/v/org.kosit/validator)](https://img.shields.io/maven-central/v/org.kosit/validator) + - [Introduction](#introduction) - [Validation Configurations](#validation-configurations) * [Third Party Validation Configurations](#third-party-validation-configurations) From 78e5d3d4ee73291eb1fc2e3ffb7e58fa6e349ace Mon Sep 17 00:00:00 2001 From: Philip Helger Date: Wed, 3 Sep 2025 16:22:22 +0200 Subject: [PATCH 2/6] Added badge, roadmap, contributors and license --- README.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 62 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 49a3257..208e588 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # KoSIT Validator -[![Maven Central](https://img.shields.io/maven-central/v/org.kosit/validator)](https://img.shields.io/maven-central/v/org.kosit/validator) +[![Maven Central](https://img.shields.io/maven-central/v/org.kosit/validator)](https://central.sonatype.com/artifact/org.kosit/validator) +[![Apache 2.0 license](https://img.shields.io/badge/license-Apache%202-blue)](https://www.apache.org/licenses/LICENSE-2.0) + - [Introduction](#introduction) - [Validation Configurations](#validation-configurations) @@ -13,14 +15,14 @@ ## Introduction -The validator is an XML validation engine to validate and process XML files in various formats. It basically does the following in order: +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. +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. @@ -28,7 +30,7 @@ See [architecture](docs/architecture.md) for information about the whole validat ## Validation configurations -The validator is just an engine and does not know anything about XML documents and has no own validation rules. +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. @@ -45,7 +47,7 @@ Here are two public third party validation configurations available which might ## Usage -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 library embedded within a custom application @@ -75,7 +77,7 @@ 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: +The Validator can also be used in own Java Applications via the API. An example use of the API as follows: ```java Path scenarios = Paths.get("scenarios.xml"); @@ -91,8 +93,7 @@ Result validationResult = validator.checkInput(document); 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. +as that dependency is marked `optional` in this project and will thus not be resolved transitively. ### Daemon-Mode @@ -107,9 +108,59 @@ The [daemon documentation](./docs/daemon.md) shows more usage details and furthe ## Packages -The validator distribution contains the following artifacts: +The Validator distribution contains the following artifacts: 1. **validator-``.jar**: Java library for embedded use within an application -1. **validator-`-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-`-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-``-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-``-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 + +## Installation + +The Validator distribution can be publicly download from the following sources: + +* 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 + + org.kosit + validator + x.y.z + +``` + +To use the standalone version with Maven coordinates, add the respective classifier: + +```xml + + org.kosit + validator + x.y.z + standalone + +``` + +## Roadmap + +This section describes the next steps planned in the Validator development. + +* Release version 1.6.0 based on Java 11 and using Jakarta 4.x. - Autumn 2025 + * Drop support of version 1.5.x when version 1.6 is released +* 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). From 52e42fe6dc99e96e8f3298c4158d92fe23eedd56 Mon Sep 17 00:00:00 2001 From: Philip Helger Date: Wed, 3 Sep 2025 16:23:12 +0200 Subject: [PATCH 3/6] Removed ToC --- README.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/README.md b/README.md index 208e588..de3595e 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,6 @@ [![Apache 2.0 license](https://img.shields.io/badge/license-Apache%202-blue)](https://www.apache.org/licenses/LICENSE-2.0) -- [Introduction](#introduction) -- [Validation Configurations](#validation-configurations) - * [Third Party Validation Configurations](#third-party-validation-configurations) -- [Usage](#usage) - * [Standalone Command-Line Interface](#standalone-command-line-interface) - * [Application User Interface (API / embedded usage)](#application-user-interface--api---embedded-usage-) - * [Daemon-Mode](#daemon-mode) -- [Packages](#packages) - ## Introduction The Validator is an XML validation engine to validate and process XML files in various formats. It basically does the following in order: From 93a64223b8d705867794542aab0c459f5c2c6b7a Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Thu, 4 Sep 2025 12:07:23 +0200 Subject: [PATCH 4/6] minor grammar in README.md (cherry picked from commit a96751e08f2b7d95cdd8d47a0a6bfa3b5ef7ef9c) Co-authored-by: Renzo Kottmann --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index de3595e..355550f 100644 --- a/README.md +++ b/README.md @@ -108,7 +108,7 @@ The Validator distribution contains the following artifacts: ## Installation -The Validator distribution can be publicly download from the following sources: +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 From 1ed9377b8366b5357658853b050126790ba80a03 Mon Sep 17 00:00:00 2001 From: yunussozeri <124086013+yunussozeri@users.noreply.github.com> Date: Mon, 8 Sep 2025 14:43:51 +0200 Subject: [PATCH 5/6] Update links to source code to current locations The links were old and not redirecting to the correct location --- docs/api.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/docs/api.md b/docs/api.md index caa93fe..5e03c85 100644 --- a/docs/api.md +++ b/docs/api.md @@ -92,25 +92,26 @@ public class StandardExample { ``` The `Result` interface has convenience methods to retrieve details about XSD validation errors and Schematron messages and other processing results. See -[Result.java](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/Result.java) for details. +[Result.java](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/Result.java) for details. + Initializing all XML artifacts and XSLT-executables is expensive. The `Check` instance is *threadsafe* and keeps all artifacts. Therefore, we recommend the re-use of a `Check` instance. -Beside the validator's configuration the only input are instances of [Input](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/Input.java) -which can be created by various methods of the [InputFactory](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/InputFactory.java). -The [InputFactory](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/InputFactory.java) +Beside the validator's configuration the only input are instances of [Input](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/Input.java) +which can be created by various methods of the [InputFactory](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/InputFactory.java). +The [InputFactory](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/InputFactory.java) calculates a hash sum for each Input which is also written to the Report. _SHA-256_ from the JDK is the default algorithm. -It can be changed using other `read`-methods of [InputFactory](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/InputFactory.java). +It can be changed using other `read`-methods of [InputFactory](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/InputFactory.java). -The main interface [Check.java](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/Check.java) -allows using a batch interface (processing list of [Inputs](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/Input.java)). +The main interface [Check.java](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/Check.java) +allows using a batch interface (processing list of [Inputs](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/Input.java)). However, there is no parallel processing implemented at the moment. ## Accept Recommendation and Accept Match -A tri-state object [AcceptRecommendation](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/AcceptRecommendation.java) -can be retrieved from the [Result](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/Result.java) using `getAcceptRecommendation()`. +A tri-state object [AcceptRecommendation](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/AcceptRecommendation.java) +can be retrieved from the [Result](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/Result.java) using `getAcceptRecommendation()`. The three defined states are: @@ -195,15 +196,15 @@ When using XML related technologies you are supposed to handle certain security * allows loading/resolving only from a configured local content repository (a specific folder) * tries to prevent known XML security issues (see [OWASP XML_Security_Cheat_Sheet.html](https://cheatsheetseries.owasp.org/cheatsheets/XML_Security_Cheat_Sheet.html)) -However, you can configure certain aspects related to resolving and security yourself. The validator uses a single interface for accessing or creating the necessary XML API objects like `SchemaFactory`, `Validator`,`URIResolver` or `Processor`: [ResolvingConfigurationStrategy.java](https://github.com/itplr-kosit/validator/tree/master/src/main/java/de/kosit/validationtool/api/ResolvingConfigurationStrategy.java) +However, you can configure certain aspects related to resolving and security yourself. The validator uses a single interface for accessing or creating the necessary XML API objects like `SchemaFactory`, `Validator`,`URIResolver` or `Processor`: [ResolvingConfigurationStrategy.java](https://github.com/itplr-kosit/validator/tree/main/src/main/java/de/kosit/validationtool/api/ResolvingConfigurationStrategy.java) There are 3 implementations available out of the box: -1. [StrictRelativeResolvingStrategy.java](https://github.com/itplr-kosit/validator/tree/master/src/main/java/de/kosit/validationtool/impl/xml/StrictRelativeResolvingStrategy.java) +1. [StrictRelativeResolvingStrategy.java](https://github.com/itplr-kosit/validator/tree/main/src/main/java/de/kosit/validationtool/impl/xml/StrictRelativeResolvingStrategy.java) which is the **default**, prevents known XML attacks and only allows loading from a specific local repository location -1. [StrictLocalResolvingStrategy.java](https://github.com/itplr-kosit/validator/tree/master/src/main/java/de/kosit/validationtool/impl/xml/StrictLocalResolvingStrategy.java) +1. [StrictLocalResolvingStrategy.java](https://github.com/itplr-kosit/validator/tree/main/src/main/java/de/kosit/validationtool/impl/xml/StrictLocalResolvingStrategy.java) which opens the first strategy to load resources from local locations -1. [RemoteResolvingStrategy.java](https://github.com/itplr-kosit/validator/tree/master/src/main/java/de/kosit/validationtool/impl/xml/RemoteResolvingStrategy.java) +1. [RemoteResolvingStrategy.java](https://github.com/itplr-kosit/validator/tree/main/src/main/java/de/kosit/validationtool/impl/xml/RemoteResolvingStrategy.java) which further opens the second to load resources also from remote locations via http and https You can configure usage of one of these implementations using the `ResolvingMode` via @@ -222,6 +223,6 @@ final Configuration config = Configuration.load(URI.create("myscenarios.xml")) --- -:warning: **Attention:** If you decide to implement a custom strategy you need to handle XML security risks on your own. Please make sure, that you prevent XXE and other kind of attacks. Consider using [BaseResolvingStrategy.java](https://github.com/itplr-kosit/validator/tree/master/src/main/java/de/kosit/validationtool/impl/xml/BaseResolvingStrategy.java) and the protected methods within to disable certain features. +:warning: **Attention:** If you decide to implement a custom strategy you need to handle XML security risks on your own. Please make sure, that you prevent XXE and other kind of attacks. Consider using [BaseResolvingStrategy.java](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/xml/BaseResolvingStrategy.java) and the protected methods within to disable certain features. --- From 705b0b2501e8bd14e458c437de6e7472eee412db Mon Sep 17 00:00:00 2001 From: Philip Helger Date: Wed, 10 Sep 2025 14:52:29 +0200 Subject: [PATCH 6/6] Updated examples + links --- README.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 355550f..7fa37f1 100644 --- a/README.md +++ b/README.md @@ -25,13 +25,16 @@ The Validator is just an engine and does not know anything about XML documents a 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. -### Third party validation configurations +### Example validation configurations -Here are two public third party validation configurations available which might serve as examples: +Here are some public validation configurations: -* Validation Configuration for [XRechnung](http://www.xoev.de/de/xrechnung): +* 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](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 @@ -42,7 +45,7 @@ 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 a http interface +* as a daemon providing an http interface ### Standalone Command Line Interface (CLI) @@ -51,18 +54,18 @@ The Validator can be used in three different ways: The general way using the CLI is: ```shell -java -jar validator--standalone.jar -s -r +java -jar validator--standalone.jar -s [-r ] [OPTIONS] [FILE] [FILE] [FILE] ... ``` The help option displays further CLI options to customize the process: ```shell -java -jar validator--standalone.jar --help +java -jar validator--standalone.jar --help ``` -A concrete example with a specific validator configuration can be found on -[GitHub](https://github.com/itplr-kosit/validator-configuration-xrechnung) +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.