From 78e5d3d4ee73291eb1fc2e3ffb7e58fa6e349ace Mon Sep 17 00:00:00 2001 From: Philip Helger Date: Wed, 3 Sep 2025 16:22:22 +0200 Subject: [PATCH] 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).