diff --git a/README.md b/README.md index de3595e..cf6d9f7 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,24 @@ # 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) + * [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: +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. @@ -21,7 +26,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. @@ -38,7 +43,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 @@ -68,7 +73,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"); @@ -84,7 +89,8 @@ 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 @@ -99,59 +105,9 @@ 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).