From 36e425388daea76a87cfb203baba03c81bb569df Mon Sep 17 00:00:00 2001 From: Philip Helger Date: Wed, 3 Sep 2025 16:36:36 +0200 Subject: [PATCH] Updated readme --- README.md | 80 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 62 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 9e79e51..a4d4f5f 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,19 @@ # KoSIT Validator -- [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) +[![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 -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. @@ -26,7 +21,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. @@ -43,7 +38,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 @@ -73,7 +68,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"); @@ -89,8 +84,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 @@ -105,8 +99,58 @@ 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 >= 11) -1. **libs/***: directory containing all (incl. optional) dependencies of the validator +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 >= 11) +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).