mirror of
https://github.com/itplr-kosit/validator.git
synced 2026-05-25 16:55:39 +00:00
Started beter documentation in English
This commit is contained in:
Renzo Kottmann
parent
c9abbfdf0a
commit
f7b290c89a
3 changed files with 100 additions and 135 deletions
91
README.md
91
README.md
|
|
@ -36,33 +36,6 @@ Eine eigenständige Konfiguration für den Standard XGewerbeanzeige wird ebenfal
|
||||||
Der geregelte Betrieb dieser Konfiguration wird im Rahmen des Betriebs des Standards XGewerbeanzeige erfolgen.
|
Der geregelte Betrieb dieser Konfiguration wird im Rahmen des Betriebs des Standards XGewerbeanzeige erfolgen.
|
||||||
|
|
||||||
|
|
||||||
# Grundsätzlicher Ablauf einer Prüfung
|
|
||||||
|
|
||||||
Eine zu prüfende Datei durchläuft die folgenden Schritte
|
|
||||||
|
|
||||||
1. *Grundsätzliche XML-Prüfung*: Es muss sich bei der zu prüfenden Datei um wohlgeformtes XML handeln, andernfalls
|
|
||||||
werden keine weiteren Prüfungen durchgeführt und ein [Prüfbericht] mit Status *invalid* und Empfehlung
|
|
||||||
*reject* generiert.
|
|
||||||
2. *Identifikation des anzuwendenden Prüfszenarios*: Für den Dokumenttyp der zu prüfenden XML-Datei muss in der
|
|
||||||
[Konfigurationsdatei](#konfiguration-des-prüftools) ein Prüfszenario definiert sein (die Identifikation des
|
|
||||||
Dokumenttyps erfolgt durch einen XPath-Test), andernfalls werden keine weiteren Prüfungen durchgeführt und ein
|
|
||||||
[Prüfbericht] mit Status *invalid* und Empfehlung *reject* generiert.
|
|
||||||
3. *Prüfung gegen das XML-Schema des identifizierten Dokumenttyps*: Das zu prüfende Dokument muss valide bzgl. des
|
|
||||||
Schemas sein, andernfalls werden keine weiteren Prüfungen durchgeführt und ein [Prüfbericht] mit Status *invalid*
|
|
||||||
und Empfehlung *reject* generiert.
|
|
||||||
4. *Prüfung gegen die Schematron-Regeln des identifizierten Dokumenttyps*
|
|
||||||
5. *Aggregation und Bewertung der einzelnen Prüfungen* zu einem [Prüfbericht]: Die Ergebnisse der
|
|
||||||
vorherigen Schritte werden in einem einheitlichen Berichtsformat zusammengefasst und bewertet:
|
|
||||||
* Sofern mindestens einer der zuvor durchgeführten Prüfschritte einen Fehler (*error*) oder eine Warnung (*warning*)
|
|
||||||
geliefert hat, erhält der Prüfbericht den Status *invalid*, andernfalls erhält er den Status *valid*.
|
|
||||||
* Sofern einer der Prüfschritte einen Fehler geliefert hat, erhält der Prüfbericht grundsätzlich die Empfehlung
|
|
||||||
*reject*, andernfalls erhält er die Empfehlung *accept*.
|
|
||||||
* In der [Konfigurationsdatei](#konfiguration-des-prüftools) kann für einzelne Prüfregeln festgelegt werden, dass
|
|
||||||
sie für die Bewertung einer [anderen Meldungsart](#anpassung-der-fehlergrade-für-die-bewertung) zuzuordnen sind
|
|
||||||
(z. B. *warning* anstelle von *error*).
|
|
||||||
* Der Prüfbericht ist ein für die maschinelle Auswertung geeignetes XML-Dokument. Darin eingebettet ist auch eine
|
|
||||||
für menschliche Leser bestimmte HTML-Aufbereitung des Prüfergebnisses. Die Details dieser HTML-Aufbereitung können
|
|
||||||
bei Bedarf [angepasst](#anpassung-der-html-ausgabe) werden.
|
|
||||||
|
|
||||||
# Verwendung
|
# Verwendung
|
||||||
|
|
||||||
|
|
@ -199,70 +172,6 @@ sowie für Ausgabeoptionen für Ergebnisse. Sämtliche Abhängigkeiten sind im J
|
||||||
|
|
||||||
* die *Full-Distribution* enthält darüber sämtlichen weiteren Varianten des `validationtools` sowie die benötigten Abhängigkeiten.
|
* die *Full-Distribution* enthält darüber sämtlichen weiteren Varianten des `validationtools` sowie die benötigten Abhängigkeiten.
|
||||||
|
|
||||||
# Konfiguration des Prüftools
|
|
||||||
|
|
||||||
Die Konfiguration besteht aus einer Konfigurationsdatei (XML-Dokument im Namensraum
|
|
||||||
`http://www.xoev.de/de/validator/framework/1/scenarios`) sowie Resourcen (XML Schemata und XSLT-Dateien) in einem "Repository" genanntem Verzeichnis, auf welche die Konfigurationsdatei verweist.
|
|
||||||
|
|
||||||
Der Aufbau der Konfigurationsdatei ist im entsprechenden Schema [scenarios.xsd](validationtool/src/main/model/xsd/scenarios.xsd) erläutert.
|
|
||||||
|
|
||||||
## Prüfbericht
|
|
||||||
Der Aufbau des Prüfberichts ist im entsprechenden Schema [report.xsd](configurations/xrechnung/resources/report.xsd) erläutert.
|
|
||||||
Die für die maschinelle Auswertung des Prüfberichts wesentlichsten Angaben sind
|
|
||||||
|
|
||||||
* der *Konformitätsstatus* (*valid* oder *invalid*, Attribut rep:report/@valid)
|
|
||||||
* die Empfehlung zur Annahme (*accept* - Element rep:report/rep:assessment/rep:accept) oder Ablehnung
|
|
||||||
(*reject* - Element rep:report/rep:assessment/rep:reject) des geprüften
|
|
||||||
Dokuments.
|
|
||||||
|
|
||||||
|
|
||||||
## Anpassung der Fehlergrade für die Bewertung
|
|
||||||
Grundsätzlich werden für die Verarbeitungen alle Meldungen, welche aus den einzelnen
|
|
||||||
[Prüfschritten](#grundsätzlicher-ablauf-der-prüfung) resultieren, in die Rollen *error*,
|
|
||||||
*warning* und *information* übersetzt. Der Prüfbericht erhält den Konformitätstatus *valid* genau dann, wenn in der
|
|
||||||
Konfiguration ein Prüfszenario für den Dokumenttyp des zu testenden Dokuments gefunden wurde und keine Meldung mit
|
|
||||||
Status *error* oder *warning* vorliegt.
|
|
||||||
|
|
||||||
Die Erstellung dieser Bewertung ist nicht konfigurierbar.
|
|
||||||
|
|
||||||
In der Standardkonfiguration erhält der Prüfbericht genau dann die Empfehlung *accept*, wenn in der Konfiguration ein
|
|
||||||
Prüfszenario für den Dokumenttyp des zu testenden Dokuments gefunden wurde und keine Meldung mit Status *error* vorliegt.
|
|
||||||
|
|
||||||
Die Erstellung dieser Empfehlung kann *je Prüfszenario* konfiguriert werden, in dem im jeweiligen Prüfszenario in
|
|
||||||
`createReport` ein `customLevel` aufgenommen wird:
|
|
||||||
|
|
||||||
```
|
|
||||||
<scenario>
|
|
||||||
<name>EN16931 CIUS XRechnung (UBL Invoice)</name>
|
|
||||||
...
|
|
||||||
<createReport>
|
|
||||||
<resource>
|
|
||||||
<name>Prüfbericht für XRechnung</name>
|
|
||||||
<location>resources/xrechnung/xrechnung-report.xsl</location>
|
|
||||||
</resource>
|
|
||||||
<customLevel level="warning">BR-15 BR-DE-3</customLevel>
|
|
||||||
</createReport>
|
|
||||||
</scenario>
|
|
||||||
```
|
|
||||||
|
|
||||||
In diesem Beispiel werden die Fehlercodes `BR-15` (Teil der EN) und `BR-DE-3` (Teil der CIUS XRechnung) für den
|
|
||||||
Bewertungsschritt von ihrer eigentlicher Rolle *error* auf *warning* geändert. Ein Dokument, welches eine oder
|
|
||||||
beide dieser Regeln verletzt (und ansonsten keine *error*-Meldungen erzeugt) erhielte damit abweichend vom
|
|
||||||
Standardverhalten die Bewertung *accept*.
|
|
||||||
|
|
||||||
## Anpassung der HTML-Ausgabe
|
|
||||||
|
|
||||||
Die Konfiguration XRechnung erstellt XML-Prüfberichte, welche für jede Bewertung (*accept* oder *reject*-Kindelement im
|
|
||||||
Prüfbericht) genau eine HTML5-Darstellung enthalten.
|
|
||||||
|
|
||||||
Diese wird durch das XSLT-Skript `xrechnung-report.xsl` erstellt. Dieses Skript kann überschrieben werden um die
|
|
||||||
HTML-Ausgabe anzupassen. Dazu ist eine neue XSTL-Datei (z. B. `my-xrechnung-report.xsl`) zu erstellen, welche
|
|
||||||
`xrechnung-report.xsl` per `xsl:import` einbindet. Die neue XSLT-Datei ist anstelle von `xrechnung-report.xsl` in der
|
|
||||||
Konfigurationsdatei einzutragen. In der neuen XSLT-Datei kann nun das XSLT-Template `html:html` oder eines der von
|
|
||||||
diesem eingebundenen Unter-Templates `html:*` überschrieben werden.
|
|
||||||
|
|
||||||
Für weiterführende Erläuterungen wird auf die Dokumentation in der XSLT `xrechung\resources\default-report.xsl`
|
|
||||||
verwiesen.
|
|
||||||
|
|
||||||
# Qualitätssicherung
|
# Qualitätssicherung
|
||||||
|
|
||||||
|
|
|
||||||
2
docs/api.md
Normal file
2
docs/api.md
Normal file
|
|
@ -0,0 +1,2 @@
|
||||||
|
# Validator API
|
||||||
|
|
||||||
54
docs/configurations.md
Normal file
54
docs/configurations.md
Normal file
|
|
@ -0,0 +1,54 @@
|
||||||
|
# Validation Configuration
|
||||||
|
|
||||||
|
## Scenarios
|
||||||
|
|
||||||
|
The core of each validation configuration is the scenarios.xml file. The scenarios.xml itself must be valid according to the [Scenarios XML Schema](/src/main/model/xsd/scenarios.xsd) with the following namespace `http://www.xoev.de/de/validator/framework/1/scenarios`.
|
||||||
|
|
||||||
|
Several validation scenarios (`<scenario>` XML Elements can be described for each configuration.
|
||||||
|
|
||||||
|
Each scenario allows to define the matching criterion. It is an XPATH expression which must evaluate to true matched against the test xml candidate. Only then this scenario will apply to the test candidate.
|
||||||
|
|
||||||
|
Within a scenario you can define the XML Schema and several Schematrons against which a test xml candidate has to be validated. You can give these a name and define where to find the resources/artifacts for validation.
|
||||||
|
|
||||||
|
Lastly, you can define in an `<createReport>` element a XSLT transformation which takes the validator's report in order to create an own styled report.
|
||||||
|
|
||||||
|
If no scenario matches you can also define a XSLT transformation in `<noScenarioReport>` element.
|
||||||
|
|
||||||
|
## Validators Report
|
||||||
|
|
||||||
|
The validator's report is defined in [createReportInput.xsd](src/main/model/xsd/createReportInput.xsd) and contains all errors from all validation steps and some addional information on time of validation, engine used, the scenario which applied and a document identification.
|
||||||
|
|
||||||
|
In general all errors will be classified in the following levels:
|
||||||
|
|
||||||
|
* *warning*,
|
||||||
|
* *error*, or
|
||||||
|
* *fatal error*
|
||||||
|
|
||||||
|
### Customization of error levels
|
||||||
|
|
||||||
|
In each single sceanrio each error level can be configured to the following error types
|
||||||
|
|
||||||
|
* error
|
||||||
|
* warning
|
||||||
|
* information
|
||||||
|
|
||||||
|
This can be done by adding `customLevel` elements in
|
||||||
|
`createReport`.
|
||||||
|
|
||||||
|
Here is an example:
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<scenario>
|
||||||
|
<name>EN16931 CIUS XRechnung (UBL Invoice)</name>
|
||||||
|
...
|
||||||
|
<createReport>
|
||||||
|
<resource>
|
||||||
|
<name>Prüfbericht für XRechnung</name>
|
||||||
|
<location>resources/xrechnung/xrechnung-report.xsl</location>
|
||||||
|
</resource>
|
||||||
|
<customLevel level="warning">BR-15</customLevel>
|
||||||
|
</createReport>
|
||||||
|
</scenario>
|
||||||
|
```
|
||||||
|
|
||||||
|
Here the errors reported by violating the schematron rule `BR/15` are translated from *error* to *warning*.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue