diff --git a/CHANGELOG.md b/CHANGELOG.md index d07d409..944fd78 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + ## next version (unreleased) ### Added @@ -15,21 +16,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Inputs are NOT read into memory (e.g. Byte-Array) prior processing within the validator. This reduces memory consumption. -## 1.2.0 (unreleased) +## 1.2.0 + ### Added -- Provide access to schematron result through Result.java +- Provide access to schematron result through [Result.java](https://github.com/itplr-kosit/validator/blob/master/src/main/java/de/kosit/validationtool/api/Result.java) - *Result#getFailedAsserts()* returns a list of failed asserts found by schematron - *Result#isSchematronValid()* convinience access to evaluate whether schematron was processed without any *FailedAsserts* - ### Changed -- *getAcceptRecommendation()* does not _only_ work when _acceptMatch_ is configured in the scenario - - schema correct is a precondion, of the checked instance is not valid, this evaluates to _REJECTED_ +- *Result#getAcceptRecommendation()* does not _only_ work when _acceptMatch_ is configured in the scenario + - schema correctness is a precondition, if the checked instance is not valid, this evaluates to _REJECTED_ - if _acceptMatch_ is configured, the result is based on the boolean result of the xpath expression evaluated against the generated report - if *no* _acceptMatch_ is configured, the result is based on evaluation of schema and schematron correctness - _UNDEFINED_ is only returned, when processing is stopped somehow -- *isAcceptable()* can no evaluate to true, when no _acceptMatch_ is configured (see above) +- *Result#isAcceptable()* can now evaluate to true, when no _acceptMatch_ is configured (see above) ## 1.1.3 diff --git a/README.md b/README.md index 832ddf6..483ba8b 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,10 @@ java -jar validationtool--standalone.jar --help A concrete example with a specific validator configuration can be found on [GitHub](https://github.com/itplr-kosit/validator-configuration-xrechnung) +### Application User Interface (API / embedded usage) + +The validator can also be used in own Java Applications via the API. Details can be [found here](./docs/api.md). + ### Daemon-Mode You can also start the validator as an HTTP-Server. Just start it in _Daemon-Mode_ with the `-D` option. @@ -86,6 +90,4 @@ You can HTTP-POST to `/` and the response will return the report document as de Additionally there is the GET `/health` endpoint which can be used by monitoring systems. -### Application User Interface (embedded usage) -The validator can also be used in own Java Applications via the API. Details can be [found here](./docs/api.md). diff --git a/docs/api.md b/docs/api.md index e537f83..31d05ab 100644 --- a/docs/api.md +++ b/docs/api.md @@ -4,7 +4,8 @@ The Validator offers an API which allows you to integrate Validator in your own ## Dependency Management -Currently, we *do not* deploy to Maven Central or similar. Hence you need to build and optionally deploy the Validator artifacts to your own shared repository (see for example [Maven Documentation](https://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html)). +Currently, we *do not* deploy to Maven Central or similar. Hence you need to build and optionally deploy the Validator artifacts to your own +shared (or local) repository (see for example [Maven Documentation](https://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html)). ### Maven @@ -28,7 +29,8 @@ dependencies { ## Usage -Prerequisite for use is a valid [scenario definition](configurations.md) and the a folder with all necessary artifacts for validation (repository) either on the filesystem or on the classpath. +Prerequisite for use is a valid [scenario definition](configurations.md) and the a folder with all necessary artifacts for validation +(repository) either on the filesystem or on the classpath. The following example demonstrates loading scenario.xml and whole configuration from classpath and validating one XML document: @@ -81,14 +83,19 @@ public class StandardExample { } ``` -The `Result` interface has more methods to retrieve details about XSD validation errors and Schematron messages. +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. -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 an `Check` instance. - -* Batch use is serial and *not parallel* +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 an `Check` instance. The only input `de.kosit.validationtool.api.Input` which can be created by various methods of `de.kosit.validationtool.api.InputFactory`. -The `InputFactory` 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 the `read`-methods of `InputFactory`. +The `InputFactory` 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 the `read`-methods of `InputFactory`. + +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)). +However, there is no parallel processing implemented at the moment. ## Accept Recommendation and Accept Match @@ -96,14 +103,21 @@ A tri-state Object `AcceptRecommendation` can be retrieved from the `Result` usi The three defined states are: -1. `UNDEFINED` i.e. the evaluation of the overall validation could not be computed. -2. `ACCEPTABLE` i.e. the recommendation is to accept input based on the evaluation of the overall validation. -3. `REJECT` i.e. the recommendation is to reject input based on the evaluation of the overall validation. +1. `ACCEPTABLE` i.e. the recommendation is to accept input based on the evaluation of the overall validation. +1. `REJECT` i.e. the recommendation is to reject input based on the evaluation of the overall validation. +1. `UNDEFINED` i.e. the evaluation of the overall validation could not be computed (overall processing is incomplete) -By default it is `UNDEFINED`. +The accept recommendation is based on either: + +1. schema and schematron validation result +1. if configured based on _acceptMatch_ configuration of the scenario (see below) ### Accept Match in Scenario Configuration -For your own configuration you can add an `acceptMatch` element in each scenario. It can contain in XPATH expression over your own defined `Report` to compute a boolean. An XPATH expression evaluating to true will lead to an `ACCEPTABLE` amd otherwise to a `REJECT` recommendation. +For your own configuration you can add an `acceptMatch` element in each scenario. It can contain in XPATH expression over your own +defined `Report` to compute a boolean. An XPATH expression evaluating to true will lead to an `ACCEPTABLE` and otherwise to a `REJECT` +recommendation. -This allows to have own control over what validation result is to be considered acceptable for your own application context. +This allows to have control over what validation result is to be considered _acceptable_ for your own application context. E.g. you can +overrule schematron validation errors with _acceptMatch_ configuration and consider certain errors as _acceptable_. Nevertheless you can *not* +overrule schema errors with accept match. diff --git a/pom.xml b/pom.xml index eb579b7..ab51b8e 100644 --- a/pom.xml +++ b/pom.xml @@ -6,7 +6,7 @@ KoSIT XML Prüftool Implementierung de.kosit - 1.2.0-SNAPSHOT + 1.3.0-SNAPSHOT validationtool KoSIT XML Validator against XSD and Schematron based on defined scenarios.