From f7b290c89a97869c61602d950841b45cda8d04e8 Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Wed, 22 May 2019 18:08:52 +0200 Subject: [PATCH 01/19] Started beter documentation in English --- README.md | 179 ++++++++++------------------------------- docs/api.md | 2 + docs/configurations.md | 54 +++++++++++++ 3 files changed, 100 insertions(+), 135 deletions(-) create mode 100644 docs/api.md create mode 100644 docs/configurations.md diff --git a/README.md b/README.md index 39e927c..c26ab1c 100644 --- a/README.md +++ b/README.md @@ -12,12 +12,12 @@ In seiner 23. Sitzung hat der [IT-Planungsrat](https://www.it-planungsrat.de) mit [Beschluss 2017/22 (6a)](https://www.it-planungsrat.de/SharedDocs/Sitzungen/DE/2017/Sitzung_23.html?pos=3) die [Koordinierungsstelle für IT-Standards (KoSIT)](https://www.xoev.de/) im Rahmen des Betriebs des Standards XRechnung mit der dauerhaften„…Bereitstellung eines Moduls zur Konformitätsprüfung elektronischer Rechnungen als offene Referenzimplementierung sowie …“ aller zugehöriger Artefakte beauftragt. Im Rahmen dieser Beauftragung wurde die hier bereitgestellte Software "Prüftool" entwickelt und (vor-) konfiguriert. -Das Prüftool ist ein Programm, welches XML-Dateien (Dokumente) in Abhängigkeit von ihren Dokumenttypen gegen verschiedene +Das Prüftool ist ein Programm, welches XML-Dateien (Dokumente) in Abhängigkeit von ihren Dokumenttypen gegen verschiedene Validierungsregeln (XML Schema und Schematron) prüft und das Ergebnis zu einem Konformitätsbericht (Konformitätsstatus -*valid* oder *invalid*) mit einer Empfehlung zur Weiterverarbeitung (*accept*) oder Ablehnung (*reject*) aggregiert. Mittels Konfiguration kann bestimmt werden, welche der Konformitätsregeln durch ein Dokument, das zur Weiterverarbeitung empfohlen (*accept*) wird, verletzt sein dürfen. +*valid* oder *invalid*) mit einer Empfehlung zur Weiterverarbeitung (*accept*) oder Ablehnung (*reject*) aggregiert. Mittels Konfiguration kann bestimmt werden, welche der Konformitätsregeln durch ein Dokument, das zur Weiterverarbeitung empfohlen (*accept*) wird, verletzt sein dürfen. -Das Prüftool selbst ist fachunabhängig und kennt keine spezifischen Dokumentinhalte noch Validierungsregeln. -Diese werden im Rahmen einer [Prüftool-Konfiguration](#konfiguration-des-prüftools) definiert, welche zur Anwendung des Prüftools erforderlich ist. +Das Prüftool selbst ist fachunabhängig und kennt keine spezifischen Dokumentinhalte noch Validierungsregeln. +Diese werden im Rahmen einer [Prüftool-Konfiguration](#konfiguration-des-prüftools) definiert, welche zur Anwendung des Prüftools erforderlich ist. # Konfigurationen @@ -36,39 +36,12 @@ 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. -# 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 Das Prüftool steht in zwei Varianten zur Verfügung: -- als [Standalone-Version](#verwendung-als-standalone-anwendung), die von der Kommandozeile aus aufgerufen werden kann -- als [Bibliothek](#verwendung-als-bibliothek), die in eigene Anwendungen integriert werden kann +- als [Standalone-Version](#verwendung-als-standalone-anwendung), die von der Kommandozeile aus aufgerufen werden kann +- als [Bibliothek](#verwendung-als-bibliothek), die in eigene Anwendungen integriert werden kann ## Voraussetzungen Zur Ausführung und zum Durchführen des Maven-Builds wird Java 8 Update 111 oder höher benötigt. @@ -92,20 +65,20 @@ java -jar validationtool--standalone.jar -s scenarios.xml -o test/repor ``` Der Aufruf erzeugt im Verzeichnis test/reports für jede validierte Eingabedatei -einen gleichnamige [Prüfbericht]-Datei. +einen gleichnamige [Prüfbericht]-Datei. Eine Übersicht über die Eigenschaften der Testdateien in [/validator-configuration-xrechnung/src/test/instances](/validator-configuration-xrechnung/src/test/instances) findet sich in -[/validator-configuration-xrechnung/src/test/instances/assertions.xlsx](/validator-configuration-xrechnung/src/test/assertions.xlsx). +[/validator-configuration-xrechnung/src/test/instances/assertions.xlsx](/validator-configuration-xrechnung/src/test/assertions.xlsx). ## Verwendung als Bibliothek -Daneben kann das Prüftool auch in eigene Anwendungen integriert werden. +Daneben kann das Prüftool auch in eigene Anwendungen integriert werden. -Die Bibliothek steht derzeit noch *nicht* im Maven-Central-Repository zur Verfügung. Sie muss manuell im lokalen oder -unternehmensweiten Maven-Repository bereitgestellt werden (siehe [vgl. Maven Dokumentation](https://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html)). +Die Bibliothek steht derzeit noch *nicht* im Maven-Central-Repository zur Verfügung. Sie muss manuell im lokalen oder +unternehmensweiten Maven-Repository bereitgestellt werden (siehe [vgl. Maven Dokumentation](https://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html)). - -* Maven + +* Maven ``` de.kosit @@ -120,9 +93,9 @@ dependencies { } ``` -Voraussetzung für die Verwendung ist eine valide Prüfszenarien-Definition (xml-Datei) und das dazugehörige Repository +Voraussetzung für die Verwendung ist eine valide Prüfszenarien-Definition (xml-Datei) und das dazugehörige Repository mit den von den definierten Szenarien benötigten Artefakten. Der folgende Quellcode zeigt die Erzeugung einer neuen -Prüf-Instanz: +Prüf-Instanz: ```java //Vorbereitung der Konfiguration @@ -137,8 +110,8 @@ Check implemenation = new DefaultCheck(config); Weitere Konfigurationsoption ist der Pfad zum Repository. Standardmäßig wird das Repository relativ zur Szenarien-Defintion unter "repository" gesucht. -Die so erzeugte Prüfinstanz initialisiert sämtliche Szenarien und deren Prüfartefakte. Ein etwaiger Konfigurationsfehler -wird frühzeitig mitgeteilt. +Die so erzeugte Prüfinstanz initialisiert sämtliche Szenarien und deren Prüfartefakte. Ein etwaiger Konfigurationsfehler +wird frühzeitig mitgeteilt. Die eigentlich Prüfung erfolgt mit den beiden Methoden des `Check`-Interfaces: @@ -158,18 +131,18 @@ List reports = pruefer.implemenation(toCheck); ``` Eine einmal initialisierte Prüfinstanz ist *threadsafe* und kann beliebig oft wieder verwendet -werden. XML-Artefakte wie Schema oder XSLT-Executables werden bei Instantiierung des `DefaultCheck` initialisiert und +werden. XML-Artefakte wie Schema oder XSLT-Executables werden bei Instantiierung des `DefaultCheck` initialisiert und wiederverwendet. Da diese Objekte relativ aufwändig zu Erzeugen sind, empfielt sich die Wiederverwendung der `Check`-Instanz. Die Batch-Verarbeitung erfolgt grundsätzlich seriell. Der `DefaultCheck` implementiert *keine Parallelverarbeitung*. Einziges Eingabeobjekt ist `Input`, welches sich mit den verschiedenen Methoden der `InputFactory` aus div. Eingabe-Resourcen erzeugen lässt. Die InputFactory erzeugt für jedes Eingabe-Objekt eine Prüfsumme, die im Report mitgeführt wird. Der -verwendete Algorithmus ist über die `read`-Methoden der `InputFactory` definierbar. Standardmäßig wird _SHA-256_ des JDK +verwendete Algorithmus ist über die `read`-Methoden der `InputFactory` definierbar. Standardmäßig wird _SHA-256_ des JDK verwendet ## Verwendung des Daemon-Mode -Das Prüftool stellt auch eine HTTP-Schnittstelle bereit, über die die Funktionalität angesprochen werden kann. Dazu wird die Anwendung +Das Prüftool stellt auch eine HTTP-Schnittstelle bereit, über die die Funktionalität angesprochen werden kann. Dazu wird die Anwendung im _Daemon-Mode_ gestartet: @@ -177,143 +150,79 @@ im _Daemon-Mode_ gestartet: java -jar validationtool--standalone.jar -s -D ``` -In der Default-Konfiguration stellt dieser Aufruf einen HTTP-Server unter _localhost_ und Port 8080 bereit. +In der Default-Konfiguration stellt dieser Aufruf einen HTTP-Server unter _localhost_ und Port 8080 bereit. Host und Port lassen sich anpassen: ```shell -java -jar validationtool--standalone.jar -s -D -H 192.168.1.x -P 8081 +java -jar validationtool--standalone.jar -s -D -H 192.168.1.x -P 8081 ``` -Im Daemon-Mode nimmt der HTTP-Server POST-Anfragen unter `/` entgegen, verarbeitet den darüber bereitgestellten Prüfling und gibt das Ergebnis-Dokument als Antwort zurück. +Im Daemon-Mode nimmt der HTTP-Server POST-Anfragen unter `/` entgegen, verarbeitet den darüber bereitgestellten Prüfling und gibt das Ergebnis-Dokument als Antwort zurück. Zur Integration in Monitoring-Systeme wird eine Health-Check angeboten. Dieser ist über einen GET-Request unter `/health` erreichbar. # Build-Anweisungen -Das Projekt wird mit Apache Maven gebaut. +Das Projekt wird mit Apache Maven gebaut. Mittels `mvn install` werden im Unterverzeichnis `dist` zwei Pakete gebaut: -* die *Standalone-Distribution* enthält das Uber-Jar mit allen Klassen zur Verarbeitung von Eingaben aus der Kommandozeile, +* die *Standalone-Distribution* enthält das Uber-Jar mit allen Klassen zur Verarbeitung von Eingaben aus der Kommandozeile, sowie für Ausgabeoptionen für Ergebnisse. Sämtliche Abhängigkeiten sind im Jar gebundlet und das Jar-File ist 'ausführbar'. * 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: - -``` - - EN16931 CIUS XRechnung (UBL Invoice) - ... - - - Prüfbericht für XRechnung - resources/xrechnung/xrechnung-report.xsl - - BR-15 BR-DE-3 - - -``` - -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 ## Umgesetzte QS-Maßnahmen ### Automatische Unit-Tests (Java-Code) -* Die korrekte Funktionsweise des Prüftools wird durch mehr als 60 Unit-Test überprüft. -* Die Unit-Tests sind Teil des bereitgestellten Codes und werden durch den Maven-Build automatisch ausgeführt. +* Die korrekte Funktionsweise des Prüftools wird durch mehr als 60 Unit-Test überprüft. +* Die Unit-Tests sind Teil des bereitgestellten Codes und werden durch den Maven-Build automatisch ausgeführt. * Die Unit-Tests decken alle grundsätzlichen Funktionen des Prüftools ab. Daneben wird das korrekte Verhalten der - Anwendung bei verschiedenen Fehleingaben überprüft und nachgewiesen. -* Die Testabdeckung (Coverage) liegt derzeit bei ca. 85% des Java-Codes. + Anwendung bei verschiedenen Fehleingaben überprüft und nachgewiesen. +* Die Testabdeckung (Coverage) liegt derzeit bei ca. 85% des Java-Codes. Diese Abdeckung wird mittels der Bibliothek jacoco automatisch ermittelt und zeigt, dass alle wesentlichen Funktionen - durch Tests überprüft werden. - Die verbleibenden 15% lassen sich fast ausschließlich auf Fehlerbedingungen (Exceptions) zurückführen, + durch Tests überprüft werden. + Die verbleibenden 15% lassen sich fast ausschließlich auf Fehlerbedingungen (Exceptions) zurückführen, die in der Praxis auch bei Fehleingaben nicht auftreten können und entsprechend durch keine Unit-Tests durchlaufen - werden. + werden. ### Automatische Code-Analyse (Java-Code) * Der Quellcode wird dauerhaft und automatisch durch das weit verbreitete System [Sonar](https://www.sonarqube.org/) zur - statischen Code-Analyse geprüft. -* Das Prüftool wird von Sonar mit aktuell ca 1.800 Zeilen Quellcode als klein (S) eingestuft. -* Es existieren aktuelle 7 "Code Smells" und 3 "False Positives". -* Sämtliche „Code Smells“ sind auf nicht abgetestete Bedingungen (siehe oben) zurückzuführen. + statischen Code-Analyse geprüft. +* Das Prüftool wird von Sonar mit aktuell ca 1.800 Zeilen Quellcode als klein (S) eingestuft. +* Es existieren aktuelle 7 "Code Smells" und 3 "False Positives". +* Sämtliche „Code Smells“ sind auf nicht abgetestete Bedingungen (siehe oben) zurückzuführen. * Ein Beispiel für ein "False Positive" ist "Illegale Ausgabe auf STDout", was jedoch eine konkrete Anforderung an das - Prüftool ist. + Prüftool ist. * In den Aspekten "Reliability", "Security" und "Maintainability" wird der Quellcode jeweils mit dem bestmöglichen - [Rating](https://docs.sonarqube.org/display/SONAR/Metric+Definitions) "A" bewertet. + [Rating](https://docs.sonarqube.org/display/SONAR/Metric+Definitions) "A" bewertet. ### Berücksichtigung von Best Practices für XML-Security * Es wurden explizit Best Practices für die sichere XML-Verarbeitung mit Java (XML, XML Schema, XSLT) berücksichtigt, um beispielsweise XXE (XML eXternal Entity) Attacken und allgemein externe Referenzierungen (Entities, XIncludes) - auzuschließen. - + auzuschließen. + ### End-to-End-Testsuite für die Prüftool-Konfiguration XRechnung * Um die korrekte Funktion der Prüftool-Konfiguration XRechnung zu testen, wurde eine Suite aus 10 Testdokumenten und insgesamt 310 prüfbaren Aussagen (Assertions) über die resultierenden Prüfberichte erstellt. * Durch diese Testsuite werden, ausgehend von dem Prüfbericht-Schemas alle möglichen Optionen und Auswahlmöglichkeiten - mindestens je einmal positiv und einmal negativ getestet. + mindestens je einmal positiv und einmal negativ getestet. * Diese Zusicherungen können vom Prüftool selbst mittels des Schalter `--implemenation-assertions` automatisch geprüft werden. * Zudem wird die Integrität aller erstellten Prüfberichte automatisch gegen das Schema (XML Schema und - Schematron-Regeln) des Prüfberichts getestet. -* Für weitere Details siehe [xrechnung/test/readme.txt](configurations/xrechnung/test/readme.txt). + Schematron-Regeln) des Prüfberichts getestet. +* Für weitere Details siehe [xrechnung/test/readme.txt](configurations/xrechnung/test/readme.txt). ## Noch nicht umgesetzte QS-Maßnahmen ### Internes Security-Audit (Java-Code) -Ein abschließendes Security Audit durch den Dienstleister läuft noch und wird voraussichtlich in der KW40 abgeschlossen sein. +Ein abschließendes Security Audit durch den Dienstleister läuft noch und wird voraussichtlich in der KW40 abgeschlossen sein. ### Fachlicher Test der Prüftool-Konfiguration XRechnung Die Korrektheit der in der Prüftool-Konfiguration XRechnung enthaltenen Schematron-Dateien bzw. der aus ihnen erstellten diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..8f39b3f --- /dev/null +++ b/docs/api.md @@ -0,0 +1,2 @@ +# Validator API + diff --git a/docs/configurations.md b/docs/configurations.md new file mode 100644 index 0000000..de8d601 --- /dev/null +++ b/docs/configurations.md @@ -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 (`` 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 `` 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 `` 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 + + EN16931 CIUS XRechnung (UBL Invoice) + ... + + + Prüfbericht für XRechnung + resources/xrechnung/xrechnung-report.xsl + + BR-15 + + +``` + +Here the errors reported by violating the schematron rule `BR/15` are translated from *error* to *warning*. From a5f5d610777bee4f98e33d637558d6f4a2567ae5 Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Tue, 28 May 2019 15:27:04 +0200 Subject: [PATCH 02/19] some more doc --- README.md | 69 -------------------------------------- docs/api.md | 75 ++++++++++++++++++++++++++++++++++++++++++ docs/configurations.md | 2 +- 3 files changed, 76 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index c26ab1c..1b2af41 100644 --- a/README.md +++ b/README.md @@ -70,76 +70,7 @@ Eine Übersicht über die Eigenschaften der Testdateien in [/validator-configuration-xrechnung/src/test/instances](/validator-configuration-xrechnung/src/test/instances) findet sich in [/validator-configuration-xrechnung/src/test/instances/assertions.xlsx](/validator-configuration-xrechnung/src/test/assertions.xlsx). -## Verwendung als Bibliothek -Daneben kann das Prüftool auch in eigene Anwendungen integriert werden. -Die Bibliothek steht derzeit noch *nicht* im Maven-Central-Repository zur Verfügung. Sie muss manuell im lokalen oder -unternehmensweiten Maven-Repository bereitgestellt werden (siehe [vgl. Maven Dokumentation](https://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html)). - - - -* Maven -``` - - de.kosit - validationtool - 1.0.0 - -``` -* Gradle -``` -dependencies { - compile group: 'de.kosit', name: 'validationtool', version: '1.0.0' -} -``` - -Voraussetzung für die Verwendung ist eine valide Prüfszenarien-Definition (xml-Datei) und das dazugehörige Repository -mit den von den definierten Szenarien benötigten Artefakten. Der folgende Quellcode zeigt die Erzeugung einer neuen -Prüf-Instanz: - -```java -//Vorbereitung der Konfiguration -URI scenarios = URI.create("scenarios.xml"); -CheckConfiguration config = new CheckConfiguration(); -config.setScenarioDefinition(scenarios); - -//Instanziierung der DefaultCheck-Implementierung -Check implemenation = new DefaultCheck(config); -``` - -Weitere Konfigurationsoption ist der Pfad zum Repository. Standardmäßig wird das Repository relativ zur Szenarien-Defintion -unter "repository" gesucht. - -Die so erzeugte Prüfinstanz initialisiert sämtliche Szenarien und deren Prüfartefakte. Ein etwaiger Konfigurationsfehler -wird frühzeitig mitgeteilt. - -Die eigentlich Prüfung erfolgt mit den beiden Methoden des `Check`-Interfaces: - -```java -... -Check pruefer = new DefaultCheck(config); - -//einzelne Datei prüfen -Input pruefKandidat = InputFactory.read(new File("rechnung.xml")); -Document report = pruefer.implemenation(pruefKandidat); - -//Batch-Prüfung -List files = Files.list(Paths.get("rechnungen")).map(path -> path.toFile()).collect(Collectors.toList()); -List toCheck = files.stream().map(InputFactory::read).collect(Collectors.toList()); -List reports = pruefer.implemenation(toCheck); - -``` - -Eine einmal initialisierte Prüfinstanz ist *threadsafe* und kann beliebig oft wieder verwendet -werden. XML-Artefakte wie Schema oder XSLT-Executables werden bei Instantiierung des `DefaultCheck` initialisiert und -wiederverwendet. Da diese Objekte relativ aufwändig zu Erzeugen sind, empfielt sich die Wiederverwendung der `Check`-Instanz. - -Die Batch-Verarbeitung erfolgt grundsätzlich seriell. Der `DefaultCheck` implementiert *keine Parallelverarbeitung*. - -Einziges Eingabeobjekt ist `Input`, welches sich mit den verschiedenen Methoden der `InputFactory` aus div. Eingabe-Resourcen -erzeugen lässt. Die InputFactory erzeugt für jedes Eingabe-Objekt eine Prüfsumme, die im Report mitgeführt wird. Der -verwendete Algorithmus ist über die `read`-Methoden der `InputFactory` definierbar. Standardmäßig wird _SHA-256_ des JDK -verwendet ## Verwendung des Daemon-Mode Das Prüftool stellt auch eine HTTP-Schnittstelle bereit, über die die Funktionalität angesprochen werden kann. Dazu wird die Anwendung diff --git a/docs/api.md b/docs/api.md index 8f39b3f..dfbd462 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,2 +1,77 @@ # Validator API +The Validator offers an API which allows you to integrate Validator in your own applications. + +## 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)). + +### Maven +Then you can declare the dependency as follows: + +```xml + + de.kosit + validationtool + ${validator.version} + +``` +### Gradle + +```js +dependencies { + compile group: 'de.kosit', name: 'validationtool', version: '1.0.0' +} +``` + +## Usage + + + +Voraussetzung für die Verwendung ist eine valide Prüfszenarien-Definition (xml-Datei) und das dazugehörige Repository +mit den von den definierten Szenarien benötigten Artefakten. Der folgende Quellcode zeigt die Erzeugung einer neuen +Prüf-Instanz: + +```java +//Vorbereitung der Konfiguration +URI scenarios = URI.create("scenarios.xml"); +CheckConfiguration config = new CheckConfiguration(); +config.setScenarioDefinition(scenarios); + +//Instanziierung der DefaultCheck-Implementierung +Check implemenation = new DefaultCheck(config); +``` + +Weitere Konfigurationsoption ist der Pfad zum Repository. Standardmäßig wird das Repository relativ zur Szenarien-Defintion +unter "repository" gesucht. + +Die so erzeugte Prüfinstanz initialisiert sämtliche Szenarien und deren Prüfartefakte. Ein etwaiger Konfigurationsfehler +wird frühzeitig mitgeteilt. + +Die eigentlich Prüfung erfolgt mit den beiden Methoden des `Check`-Interfaces: + +```java +... +Check pruefer = new DefaultCheck(config); + +//einzelne Datei prüfen +Input pruefKandidat = InputFactory.read(new File("rechnung.xml")); +Document report = pruefer.implemenation(pruefKandidat); + +//Batch-Prüfung +List files = Files.list(Paths.get("rechnungen")).map(path -> path.toFile()).collect(Collectors.toList()); +List toCheck = files.stream().map(InputFactory::read).collect(Collectors.toList()); +List reports = pruefer.implemenation(toCheck); + +``` + +Eine einmal initialisierte Prüfinstanz ist *threadsafe* und kann beliebig oft wieder verwendet +werden. XML-Artefakte wie Schema oder XSLT-Executables werden bei Instantiierung des `DefaultCheck` initialisiert und +wiederverwendet. Da diese Objekte relativ aufwändig zu Erzeugen sind, empfielt sich die Wiederverwendung der `Check`-Instanz. + +Die Batch-Verarbeitung erfolgt grundsätzlich seriell. Der `DefaultCheck` implementiert *keine Parallelverarbeitung*. + +Einziges Eingabeobjekt ist `Input`, welches sich mit den verschiedenen Methoden der `InputFactory` aus div. Eingabe-Resourcen +erzeugen lässt. Die InputFactory erzeugt für jedes Eingabe-Objekt eine Prüfsumme, die im Report mitgeführt wird. Der +verwendete Algorithmus ist über die `read`-Methoden der `InputFactory` definierbar. Standardmäßig wird _SHA-256_ des JDK +verwendet diff --git a/docs/configurations.md b/docs/configurations.md index de8d601..142b901 100644 --- a/docs/configurations.md +++ b/docs/configurations.md @@ -51,4 +51,4 @@ Here is an example: ``` -Here the errors reported by violating the schematron rule `BR/15` are translated from *error* to *warning*. +Here the errors reported by violating the schematron rule `BR-15` are translated from *error* to *warning*. From 3201735eec6e09ae1b637eba38c25e49dfee9a70 Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Thu, 20 Jun 2019 14:48:54 +0200 Subject: [PATCH 03/19] Minor typos --- docs/configurations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configurations.md b/docs/configurations.md index 142b901..420cd40 100644 --- a/docs/configurations.md +++ b/docs/configurations.md @@ -16,7 +16,7 @@ If no scenario matches you can also define a XSLT transformation in ` Date: Thu, 20 Jun 2019 14:49:12 +0200 Subject: [PATCH 04/19] More English translation --- docs/api.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/docs/api.md b/docs/api.md index dfbd462..d0e576e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -7,6 +7,7 @@ The Validator offers an API which allows you to integrate Validator in your own 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)). ### Maven + Then you can declare the dependency as follows: ```xml @@ -16,6 +17,7 @@ Then you can declare the dependency as follows: ${validator.version} ``` + ### Gradle ```js @@ -26,10 +28,9 @@ dependencies { ## Usage +Prerequisite for use is a valid [scenario definition](configurations.md) and the a folder with all necessary artifacts for validation (repository). - -Voraussetzung für die Verwendung ist eine valide Prüfszenarien-Definition (xml-Datei) und das dazugehörige Repository -mit den von den definierten Szenarien benötigten Artefakten. Der folgende Quellcode zeigt die Erzeugung einer neuen +The following example demonstrates Der folgende Quellcode zeigt die Erzeugung einer neuen Prüf-Instanz: ```java @@ -65,13 +66,9 @@ List reports = pruefer.implemenation(toCheck); ``` -Eine einmal initialisierte Prüfinstanz ist *threadsafe* und kann beliebig oft wieder verwendet -werden. XML-Artefakte wie Schema oder XSLT-Executables werden bei Instantiierung des `DefaultCheck` initialisiert und -wiederverwendet. Da diese Objekte relativ aufwändig zu Erzeugen sind, empfielt sich die Wiederverwendung der `Check`-Instanz. +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. -Die Batch-Verarbeitung erfolgt grundsätzlich seriell. Der `DefaultCheck` implementiert *keine Parallelverarbeitung*. +* Batch use is serial and *not parallel* -Einziges Eingabeobjekt ist `Input`, welches sich mit den verschiedenen Methoden der `InputFactory` aus div. Eingabe-Resourcen -erzeugen lässt. Die InputFactory erzeugt für jedes Eingabe-Objekt eine Prüfsumme, die im Report mitgeführt wird. Der -verwendete Algorithmus ist über die `read`-Methoden der `InputFactory` definierbar. Standardmäßig wird _SHA-256_ des JDK -verwendet +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`. From 7727559cf608414eaa3585cd66ff6b89914c2c6b Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Thu, 20 Jun 2019 16:40:12 +0200 Subject: [PATCH 05/19] More English translation and trimming of README to essential information --- README.md | 186 +++++++++++++---------------------------- docs/about.md | 5 ++ docs/configurations.md | 2 +- docs/qs.md | 57 +++++++++++++ 4 files changed, 120 insertions(+), 130 deletions(-) create mode 100644 docs/about.md create mode 100644 docs/qs.md diff --git a/README.md b/README.md index 1b2af41..271c03c 100644 --- a/README.md +++ b/README.md @@ -1,161 +1,89 @@ -# Inhaltsverzeichnis +# Validator -- [Über das Prüftool](#über-das-prüftool) -- [Konfigurationen](#konfigurationen) -- [Grundsätzlicher Ablauf einer Prüfung](#grundsätzlicher-ablauf-einer-prüfung) -- [Verwendung](#verwendung) -- [Build-Anweisungen](#build-anweisungen) -- [Konfiguration des Prüftools](#konfiguration-des-prüftools) -- [Qualitätssicherung](#qualitätssicherung) +The validator is an XML validation-engine. It validates XML documents against XML Schema and Schematrons depending on self defined [scenarios](docs/configurations) which are used to fully configure the validation process. +The validator always outputs a [validation report in XML](docs/configurations.md#validators-report) including all validation errors and data about the validation. -# Über das Prüftool +## Releases -In seiner 23. Sitzung hat der [IT-Planungsrat](https://www.it-planungsrat.de) mit [Beschluss 2017/22 (6a)](https://www.it-planungsrat.de/SharedDocs/Sitzungen/DE/2017/Sitzung_23.html?pos=3) die [Koordinierungsstelle für IT-Standards (KoSIT)](https://www.xoev.de/) im Rahmen des Betriebs des Standards XRechnung mit der dauerhaften„…Bereitstellung eines Moduls zur Konformitätsprüfung elektronischer Rechnungen als offene Referenzimplementierung sowie …“ aller zugehöriger Artefakte beauftragt. Im Rahmen dieser Beauftragung wurde die hier bereitgestellte Software "Prüftool" entwickelt und (vor-) konfiguriert. - -Das Prüftool ist ein Programm, welches XML-Dateien (Dokumente) in Abhängigkeit von ihren Dokumenttypen gegen verschiedene -Validierungsregeln (XML Schema und Schematron) prüft und das Ergebnis zu einem Konformitätsbericht (Konformitätsstatus -*valid* oder *invalid*) mit einer Empfehlung zur Weiterverarbeitung (*accept*) oder Ablehnung (*reject*) aggregiert. Mittels Konfiguration kann bestimmt werden, welche der Konformitätsregeln durch ein Dokument, das zur Weiterverarbeitung empfohlen (*accept*) wird, verletzt sein dürfen. - -Das Prüftool selbst ist fachunabhängig und kennt keine spezifischen Dokumentinhalte noch Validierungsregeln. -Diese werden im Rahmen einer [Prüftool-Konfiguration](#konfiguration-des-prüftools) definiert, welche zur Anwendung des Prüftools erforderlich ist. - -# Konfigurationen - -Fach- bzw. Standardspezifische Prüfkonfigurationen sind in eigene Module bzw. Repositories ausgelagert. - -## Prüfkonfiguration XRechnung - -Eine eigenständige Konfiguration für den Standard [XRechnung](http://www.xoev.de/de/xrechnung) wird ebenfalls auf [GitHub bereitgestellt](https://github.com/itplr-kosit/validator-configuration-xrechnung) ([Releases](https://github.com/itplr-kosit/validator-configuration-xrechnung/releases)). Diese enthält alle notwendigen Ressourcen zu der Norm EN16931 (XML-Schema und [Schematron Regeln] (https://github.com/CenPC434/validation) u.a.) und die [XRechnung Schematron Regeln](https://github.com/itplr-kosit/xrechnung-schematron) in ihren aktuellen Versionen. - -Der geregelte Betrieb dieser Konfiguration wird im Rahmen des Betriebs des Standards XRechnung erfolgen. - -## Prüfkonfiguration XGewerbeanzeige - -Eine eigenständige Konfiguration für den Standard XGewerbeanzeige wird ebenfalls auf [GitHub bereitgestellt](https://github.com/itplr-kosit/validator-configuration-xgewerbeanzeige) ([Releases](https://github.com/itplr-kosit/validator-configuration-xgewerbeanzeige/releases)). - -Der geregelte Betrieb dieser Konfiguration wird im Rahmen des Betriebs des Standards XGewerbeanzeige erfolgen. - - - -# Verwendung +Two kind of releases are available: Das Prüftool steht in zwei Varianten zur Verfügung: -- als [Standalone-Version](#verwendung-als-standalone-anwendung), die von der Kommandozeile aus aufgerufen werden kann -- als [Bibliothek](#verwendung-als-bibliothek), die in eigene Anwendungen integriert werden kann -## Voraussetzungen -Zur Ausführung und zum Durchführen des Maven-Builds wird Java 8 Update 111 oder höher benötigt. +- als standalone/cli, die von der Kommandozeile aus aufgerufen werden kann +- als Bibliothek/api, die in eigene Anwendungen integriert werden kann +* die *Standalone-Distribution* enthält das Uber-Jar mit allen Klassen zur Verarbeitung von Eingaben aus der Kommandozeile, +sowie für Ausgabeoptionen für Ergebnisse. Sämtliche Abhängigkeiten sind im Jar gebundlet und das Jar-File ist 'ausführbar'. +* die *Full-Distribution* enthält darüber sämtlichen weiteren Varianten des `validationtools` sowie die benötigten Abhängigkeiten. -## Verwendung als Standalone-Anwendung +## Build + +### Requirements + +* Maven > 3.0.0 +* Java > 8 update 111 + +### Procedure + + `mvn install` generates two different packages in the `dist` directory: + +## Validation Configurations + +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) which are used to fully configure the validation process. + +All configurations are self-contained modules and deployed on their own. + +### Third Party Validation Configurations + +Currently, there are two public third party validation configurations available. + +* Validation Configuration for [XRechnung](http://www.xoev.de/de/xrechnung) is available on + * Source code is available on [GitHub](https://github.com/itplr-kosit/validator-configuration-xrechnung) + * [Releases](https://github.com/itplr-kosit/validator-configuration-xrechnung/releases) can also be downloaded +* Validation Configuration for XGewerbeanzeige + * Source code is available on [GitHub](https://github.com/itplr-kosit/validator-configuration-xgewerbeanzeige) + * [Releases](https://github.com/itplr-kosit/validator-configuration-xgewerbeanzeige/releases) can also be downloaded + +## Usage + +### Standalone Command-Line Interface + +The general way using the CLI is: ```shell java -jar validationtool--standalone.jar -s [OPTIONS] [FILE] [FILE] [FILE] ... ``` -Eine Liste der möglichen Optionen kann mit den Schalter `--help` angezeigt werden. +You can more CLI options by -Aufruf, um die mitgelieferten Test-Dokumente zu validieren und dabei neben den XML-Prüfberichten auch die eingebetteten -HTML-Dokumente als eingeständige Dateien auszugeben: - -``` -unzip validationtool-dist--standalone.zip -unzip validator-configuration-xrechnung__.zip -java -jar validationtool--standalone.jar -s scenarios.xml -o test/reports -h test/instances/*.xml +```shell +java -jar validationtool--standalone.jar --help ``` -Der Aufruf erzeugt im Verzeichnis test/reports für jede validierte Eingabedatei -einen gleichnamige [Prüfbericht]-Datei. -Eine Übersicht über die Eigenschaften der Testdateien in -[/validator-configuration-xrechnung/src/test/instances](/validator-configuration-xrechnung/src/test/instances) findet sich in -[/validator-configuration-xrechnung/src/test/instances/assertions.xlsx](/validator-configuration-xrechnung/src/test/assertions.xlsx). +A concrete exmaple with a specific validator configuration can be found on [GitHub](https://github.com/itplr-kosit/validator-configuration-xrechnung +### Daemon-Mode - -## Verwendung des Daemon-Mode -Das Prüftool stellt auch eine HTTP-Schnittstelle bereit, über die die Funktionalität angesprochen werden kann. Dazu wird die Anwendung -im _Daemon-Mode_ gestartet: - +You can also start the validator as an HTTP-Server. Just start it in _Daemon-Mode_ with the `-D` option. ```shell java -jar validationtool--standalone.jar -s -D ``` -In der Default-Konfiguration stellt dieser Aufruf einen HTTP-Server unter _localhost_ und Port 8080 bereit. +Per default the HTTP-Server listens on _localhost_ at Port 8080. -Host und Port lassen sich anpassen: +You can configure it with `-H` for IP Adress and `-P` for port number: ```shell java -jar validationtool--standalone.jar -s -D -H 192.168.1.x -P 8081 ``` -Im Daemon-Mode nimmt der HTTP-Server POST-Anfragen unter `/` entgegen, verarbeitet den darüber bereitgestellten Prüfling und gibt das Ergebnis-Dokument als Antwort zurück. -Zur Integration in Monitoring-Systeme wird eine Health-Check angeboten. Dieser ist über einen GET-Request unter `/health` erreichbar. +You can HTTP-POST to `/` and the response will return the report document as defined in your validator configuration. -# Build-Anweisungen +Additionally there is the GET `/health` endpoint which can be used by monitoring systems. -Das Projekt wird mit Apache Maven gebaut. +### Application User Interface -Mittels `mvn install` werden im Unterverzeichnis `dist` zwei Pakete gebaut: - -* die *Standalone-Distribution* enthält das Uber-Jar mit allen Klassen zur Verarbeitung von Eingaben aus der Kommandozeile, -sowie für Ausgabeoptionen für Ergebnisse. Sämtliche Abhängigkeiten sind im Jar gebundlet und das Jar-File ist 'ausführbar'. - -* die *Full-Distribution* enthält darüber sämtlichen weiteren Varianten des `validationtools` sowie die benötigten Abhängigkeiten. - - -# Qualitätssicherung - -## Umgesetzte QS-Maßnahmen - -### Automatische Unit-Tests (Java-Code) -* Die korrekte Funktionsweise des Prüftools wird durch mehr als 60 Unit-Test überprüft. -* Die Unit-Tests sind Teil des bereitgestellten Codes und werden durch den Maven-Build automatisch ausgeführt. -* Die Unit-Tests decken alle grundsätzlichen Funktionen des Prüftools ab. Daneben wird das korrekte Verhalten der - Anwendung bei verschiedenen Fehleingaben überprüft und nachgewiesen. -* Die Testabdeckung (Coverage) liegt derzeit bei ca. 85% des Java-Codes. - Diese Abdeckung wird mittels der Bibliothek jacoco automatisch ermittelt und zeigt, dass alle wesentlichen Funktionen - durch Tests überprüft werden. - Die verbleibenden 15% lassen sich fast ausschließlich auf Fehlerbedingungen (Exceptions) zurückführen, - die in der Praxis auch bei Fehleingaben nicht auftreten können und entsprechend durch keine Unit-Tests durchlaufen - werden. - -### Automatische Code-Analyse (Java-Code) - -* Der Quellcode wird dauerhaft und automatisch durch das weit verbreitete System [Sonar](https://www.sonarqube.org/) zur - statischen Code-Analyse geprüft. -* Das Prüftool wird von Sonar mit aktuell ca 1.800 Zeilen Quellcode als klein (S) eingestuft. -* Es existieren aktuelle 7 "Code Smells" und 3 "False Positives". -* Sämtliche „Code Smells“ sind auf nicht abgetestete Bedingungen (siehe oben) zurückzuführen. -* Ein Beispiel für ein "False Positive" ist "Illegale Ausgabe auf STDout", was jedoch eine konkrete Anforderung an das - Prüftool ist. -* In den Aspekten "Reliability", "Security" und "Maintainability" wird der Quellcode jeweils mit dem bestmöglichen - [Rating](https://docs.sonarqube.org/display/SONAR/Metric+Definitions) "A" bewertet. - -### Berücksichtigung von Best Practices für XML-Security - -* Es wurden explizit Best Practices für die sichere XML-Verarbeitung mit Java (XML, XML Schema, XSLT) berücksichtigt, um - beispielsweise XXE (XML eXternal Entity) Attacken und allgemein externe Referenzierungen (Entities, XIncludes) - auzuschließen. - -### End-to-End-Testsuite für die Prüftool-Konfiguration XRechnung - -* Um die korrekte Funktion der Prüftool-Konfiguration XRechnung zu testen, wurde eine Suite aus 10 Testdokumenten und - insgesamt 310 prüfbaren Aussagen (Assertions) über die resultierenden Prüfberichte erstellt. -* Durch diese Testsuite werden, ausgehend von dem Prüfbericht-Schemas alle möglichen Optionen und Auswahlmöglichkeiten - mindestens je einmal positiv und einmal negativ getestet. -* Diese Zusicherungen können vom Prüftool selbst mittels des Schalter `--implemenation-assertions` automatisch geprüft werden. -* Zudem wird die Integrität aller erstellten Prüfberichte automatisch gegen das Schema (XML Schema und - Schematron-Regeln) des Prüfberichts getestet. -* Für weitere Details siehe [xrechnung/test/readme.txt](configurations/xrechnung/test/readme.txt). - - -## Noch nicht umgesetzte QS-Maßnahmen - -### Internes Security-Audit (Java-Code) -Ein abschließendes Security Audit durch den Dienstleister läuft noch und wird voraussichtlich in der KW40 abgeschlossen sein. - -### Fachlicher Test der Prüftool-Konfiguration XRechnung -Die Korrektheit der in der Prüftool-Konfiguration XRechnung enthaltenen Schematron-Dateien bzw. der aus ihnen erstellten -XSLT-Kompilate wurde noch nicht systematisch geprüft, da weder die Schematron-Dateien der EN16931 noch die -Schematron-Dateien des Standards XRechnung in finalen Fassungen vorlagen. +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/about.md b/docs/about.md new file mode 100644 index 0000000..6e2eefa --- /dev/null +++ b/docs/about.md @@ -0,0 +1,5 @@ +# About + +## German + +In seiner 23. Sitzung hat der [IT-Planungsrat](https://www.it-planungsrat.de) mit [Beschluss 2017/22 (6a)](https://www.it-planungsrat.de/SharedDocs/Sitzungen/DE/2017/Sitzung_23.html?pos=3) die [Koordinierungsstelle für IT-Standards (KoSIT)](https://www.xoev.de/) im Rahmen des Betriebs des Standards XRechnung mit der dauerhaften„…Bereitstellung eines Moduls zur Konformitätsprüfung elektronischer Rechnungen als offene Referenzimplementierung sowie …“ aller zugehöriger Artefakte beauftragt. Im Rahmen dieser Beauftragung wurde die hier bereitgestellte Software "Prüftool" entwickelt und (vor-) konfiguriert. diff --git a/docs/configurations.md b/docs/configurations.md index 420cd40..60bfd33 100644 --- a/docs/configurations.md +++ b/docs/configurations.md @@ -16,7 +16,7 @@ If no scenario matches you can also define a XSLT transformation in ` Date: Fri, 21 Jun 2019 11:08:59 +0200 Subject: [PATCH 06/19] Add new file --- docs/docs/architecture.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/docs/architecture.md diff --git a/docs/docs/architecture.md b/docs/docs/architecture.md new file mode 100644 index 0000000..e69de29 From 6fa9e8080294411af46d0c98c5b830d36383174b Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Fri, 21 Jun 2019 11:09:11 +0200 Subject: [PATCH 07/19] Update architecture.md --- docs/{docs => }/architecture.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{docs => }/architecture.md (100%) diff --git a/docs/docs/architecture.md b/docs/architecture.md similarity index 100% rename from docs/docs/architecture.md rename to docs/architecture.md From 98448cdc2c8fd87b74994167a73d782b35c39898 Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Fri, 21 Jun 2019 11:24:01 +0200 Subject: [PATCH 08/19] Update architecture.md --- docs/architecture.md | 51 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/docs/architecture.md b/docs/architecture.md index e69de29..f9465e3 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -0,0 +1,51 @@ +# General Architecture + +The validator itself is just an engine which executes validation according to a certain configuration (see [configuration documentation](configuration.md)) + + + + +```mermaid + +sequenceDiagram + participant A as Alice + participant J as John + A->>J: Hello John, how are you? + J->>A: Great! + + + + +``` + + +Eine zu prüfende Datei durchläuft die folgenden Schritte + + +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. + + From 0f4520f4f2710d53f27b0cd7f84acf2463fe664b Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Fri, 21 Jun 2019 11:47:14 +0200 Subject: [PATCH 09/19] Minor typo --- docs/configurations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configurations.md b/docs/configurations.md index 60bfd33..40b6125 100644 --- a/docs/configurations.md +++ b/docs/configurations.md @@ -4,11 +4,11 @@ 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 (`` XML Elements can be described for each configuration. +Several validation scenarios (`` 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. +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 each a name and define where to find the resources/artifacts for validation. Lastly, you can define in an `` element a XSLT transformation which takes the validator's report in order to create an own styled report. From c03e16bd5a5e74d9629cf441dbb67319d4776707 Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Fri, 21 Jun 2019 11:47:37 +0200 Subject: [PATCH 10/19] Add material yet to be rewritten --- docs/architecture.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index f9465e3..b1f148a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -8,10 +8,10 @@ The validator itself is just an engine which executes validation according to a ```mermaid sequenceDiagram - participant A as Alice - participant J as John - A->>J: Hello John, how are you? - J->>A: Great! + participant e as Validator + participant c as Configuration + e ->> c: Read scenario.xml + e ->> c: Pick validation artifacts From 2f9c39fabdeb218266174580152f42766b0ec7af Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Fri, 21 Jun 2019 13:36:17 +0200 Subject: [PATCH 11/19] deleted unnecessary part --- docs/qs.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/qs.md b/docs/qs.md index db0caac..c69471d 100644 --- a/docs/qs.md +++ b/docs/qs.md @@ -44,14 +44,4 @@ Schematron-Regeln) des Prüfberichts getestet. * Für weitere Details siehe [xrechnung/test/readme.txt](configurations/xrechnung/test/readme.txt). -## Noch nicht umgesetzte QS-Maßnahmen -### Internes Security-Audit (Java-Code) - -Ein abschließendes Security Audit durch den Dienstleister läuft noch und wird voraussichtlich in der KW40 abgeschlossen sein. - -### Fachlicher Test der Prüftool-Konfiguration XRechnung - -Die Korrektheit der in der Prüftool-Konfiguration XRechnung enthaltenen Schematron-Dateien bzw. der aus ihnen erstellten -XSLT-Kompilate wurde noch nicht systematisch geprüft, da weder die Schematron-Dateien der EN16931 noch die -Schematron-Dateien des Standards XRechnung in finalen Fassungen vorlagen. From a4ac6dd930354cdc29a06d5f8ddc059af404a50c Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Fri, 21 Jun 2019 14:38:31 +0200 Subject: [PATCH 12/19] Translated and streamlines qs doc --- docs/qs.md | 50 ++++++++------------------------------------------ 1 file changed, 8 insertions(+), 42 deletions(-) diff --git a/docs/qs.md b/docs/qs.md index c69471d..6b08310 100644 --- a/docs/qs.md +++ b/docs/qs.md @@ -1,47 +1,13 @@ -# Qualitätssicherung +# Quality Management -## Umgesetzte QS-Maßnahmen +Some information on how we aim to ensure certain level of quality. -### Automatische Unit-Tests (Java-Code) +## Measures -* Die korrekte Funktionsweise des Prüftools wird durch mehr als 60 Unit-Test überprüft. -* Die Unit-Tests sind Teil des bereitgestellten Codes und werden durch den Maven-Build automatisch ausgeführt. -* Die Unit-Tests decken alle grundsätzlichen Funktionen des Prüftools ab. Daneben wird das korrekte Verhalten der - Anwendung bei verschiedenen Fehleingaben überprüft und nachgewiesen. -* Die Testabdeckung (Coverage) liegt derzeit bei ca. 85% des Java-Codes. - Diese Abdeckung wird mittels der Bibliothek jacoco automatisch ermittelt und zeigt, dass alle wesentlichen Funktionen - durch Tests überprüft werden. - Die verbleibenden 15% lassen sich fast ausschließlich auf Fehlerbedingungen (Exceptions) zurückführen, - die in der Praxis auch bei Fehleingaben nicht auftreten können und entsprechend durch keine Unit-Tests durchlaufen - werden. - -### Automatische Code-Analyse (Java-Code) - -* Der Quellcode wird dauerhaft und automatisch durch das weit verbreitete System [Sonar](https://www.sonarqube.org/) zur - statischen Code-Analyse geprüft. -* Das Prüftool wird von Sonar mit aktuell ca 1.800 Zeilen Quellcode als klein (S) eingestuft. -* Es existieren aktuelle 7 "Code Smells" und 3 "False Positives". -* Sämtliche „Code Smells“ sind auf nicht abgetestete Bedingungen (siehe oben) zurückzuführen. -* Ein Beispiel für ein "False Positive" ist "Illegale Ausgabe auf STDout", was jedoch eine konkrete Anforderung an das - Prüftool ist. -* In den Aspekten "Reliability", "Security" und "Maintainability" wird der Quellcode jeweils mit dem bestmöglichen - [Rating](https://docs.sonarqube.org/display/SONAR/Metric+Definitions) "A" bewertet. - -### Berücksichtigung von Best Practices für XML-Security - -* Es wurden explizit Best Practices für die sichere XML-Verarbeitung mit Java (XML, XML Schema, XSLT) berücksichtigt, um - beispielsweise XXE (XML eXternal Entity) Attacken und allgemein externe Referenzierungen (Entities, XIncludes) - auzuschließen. - -### End-to-End-Testsuite für die Prüftool-Konfiguration XRechnung - -* Um die korrekte Funktion der Prüftool-Konfiguration XRechnung zu testen, wurde eine Suite aus 10 Testdokumenten und - insgesamt 310 prüfbaren Aussagen (Assertions) über die resultierenden Prüfberichte erstellt. -* Durch diese Testsuite werden, ausgehend von dem Prüfbericht-Schemas alle möglichen Optionen und Auswahlmöglichkeiten - mindestens je einmal positiv und einmal negativ getestet. -* Diese Zusicherungen können vom Prüftool selbst mittels des Schalter `--implemenation-assertions` automatisch geprüft werden. -* Zudem wird die Integrität aller erstellten Prüfberichte automatisch gegen das Schema (XML Schema und - Schematron-Regeln) des Prüfberichts getestet. -* Für weitere Details siehe [xrechnung/test/readme.txt](configurations/xrechnung/test/readme.txt). +* We perform unit tests (see [source code](src/test/java/de/kosit/validationtool) ) +* We perform static code analysis using [Sonar](https://docs.sonarqube.org/display/SONAR/Metric+Definitions) +## XML-Security Best Practices + +* We follow the recommndations on best practices for JAVA XML to mitigate XML eXternal Entity (XXE) attacks and per default we do not allow external references on Entities and XIncludes \ No newline at end of file From f4c1afb0651657d284a5491347b44e512b1d638d Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Fri, 21 Jun 2019 14:44:06 +0200 Subject: [PATCH 13/19] Add OWASP recommendation link --- docs/qs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/qs.md b/docs/qs.md index 6b08310..cea4622 100644 --- a/docs/qs.md +++ b/docs/qs.md @@ -10,4 +10,4 @@ Some information on how we aim to ensure certain level of quality. ## XML-Security Best Practices -* We follow the recommndations on best practices for JAVA XML to mitigate XML eXternal Entity (XXE) attacks and per default we do not allow external references on Entities and XIncludes \ No newline at end of file +* We follow the [OWASP recommendations](https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/XML_Security_Cheat_Sheet.md) on best practices for JAVA XML to mitigate XML eXternal Entity (XXE) attacks and per default we do not allow external references on Entities and XIncludes \ No newline at end of file From f073924a8a27ceb5a823c5113d4ac2b0c0e8a43a Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Fri, 21 Jun 2019 15:37:26 +0200 Subject: [PATCH 14/19] Translation, add seq. dia, separation of concerns --- docs/architecture.md | 71 ++++++++++++++++++++------------------------ 1 file changed, 32 insertions(+), 39 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index b1f148a..2f58a86 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,51 +1,44 @@ # General Architecture -The validator itself is just an engine which executes validation according to a certain configuration (see [configuration documentation](configuration.md)) - +The validator itself is just an engine which executes validation according to a certain configuration (see [configuration documentation](docs/configurations.md)). + +The validator takes a sceanrio.xml and the configured directory with all artifacts necessary for validation (scenario repository). Then it performs +the validation and generates a report in XML format. This report is then the input to an XSLT provided by the configuration. + +## Separation of concerns + +* The purpose of the validator is to only report if an XML instance is valid or not +* A configuration can provide an XSLT which takes the validator report and generates an own report + * This report may choose to conclude acceptance of the XML instance or not + +The validator reports valid/invalid, a configuration reports acceptance/rejection! +## General process +The general process is like this: ```mermaid sequenceDiagram - participant e as Validator - participant c as Configuration - e ->> c: Read scenario.xml - e ->> c: Pick validation artifacts + participant e as Validator + participant c as Configuration + e->>+c: create ScenarioRepository + c->>-e: is available + e->>e: parse XML + e->>e: select scenario + e->>e: validate XSD + e->>e: validate Schematron + e->>e: create Validator Report + e->>+c: execute configuration report generator + e->>-c: return XPATH of acceptance message - - - ``` + +1. *XML-Parsing*: Is the XML instance valid in the basic sense. If not, validation is stopped and the validator report is returned with status *invalid*. +2. *Identifikation of applicable scenario*: The configuration must have a defined scenario which matches the XML instance (it is an XPATH expression). If no scenario matches, validation is stopped and the validator report is returned with status *invalid*. +3. *XML-Schema validation*: The XML instance must be valid according to the configured XSD. If not, validation is stopped and the validator report is returned with status *invalid*. +4. *Schematron validation* +5. *Aggregation of validation results*: All results are aggregated into the validation report: + * In case there is a single *error* or *warning* the report will have status erhält*invalid*, otherwise the status will be *valid*. -Eine zu prüfende Datei durchläuft die folgenden Schritte - - -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. - - From d7c3786b51b7560e83b513d342725752a261e80b Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Fri, 21 Jun 2019 15:39:18 +0200 Subject: [PATCH 15/19] Fixed arrow in seq. dia. --- docs/architecture.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture.md b/docs/architecture.md index 2f58a86..11ef1ed 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -30,7 +30,7 @@ sequenceDiagram e->>e: validate Schematron e->>e: create Validator Report e->>+c: execute configuration report generator - e->>-c: return XPATH of acceptance message + c->>-e: return XPATH of acceptance message ``` From 5820be63e5b758e749e3f00862a083bab8ef05f8 Mon Sep 17 00:00:00 2001 From: "Andreas Penski (init)" Date: Mon, 24 Jun 2019 14:13:56 +0200 Subject: [PATCH 16/19] #26 und #17 Doku erweitert --- README.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 0a2fcc5..e405658 100644 --- a/README.md +++ b/README.md @@ -3,18 +3,14 @@ The validator is an XML validation-engine. It validates XML documents against XML Schema and Schematrons depending on self defined [scenarios](docs/configurations) which are used to fully configure the validation process. The validator always outputs a [validation report in XML](docs/configurations.md#validators-report) including all validation errors and data about the validation. -## Releases +## Packages -Two kind of releases are available: +The validator distribution contains the following artifacts: -Das Prüftool steht in zwei Varianten zur Verfügung: - -- als standalone/cli, die von der Kommandozeile aus aufgerufen werden kann -- als Bibliothek/api, die in eigene Anwendungen integriert werden kann - -* die *Standalone-Distribution* enthält das Uber-Jar mit allen Klassen zur Verarbeitung von Eingaben aus der Kommandozeile, -sowie für Ausgabeoptionen für Ergebnisse. Sämtliche Abhängigkeiten sind im Jar gebundlet und das Jar-File ist 'ausführbar'. -* die *Full-Distribution* enthält darüber sämtlichen weiteren Varianten des `validationtools` sowie die benötigten Abhängigkeiten. +1. **validator-``.jar**: Java library for embedded use within an application +1. **validator-`-standalone**: 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**: 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 ## Build @@ -48,6 +44,13 @@ Currently, there are two public third party validation configurations available. ## Usage +The validator is designed to be used in different 3 ways: + +- as standalone application running from the cli +- as library embedded within a custom application +- as a daemon providing a http interface + + ### Standalone Command-Line Interface The general way using the CLI is: @@ -84,6 +87,6 @@ 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 +### 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). From 11fb43cb372f5aa09d6b601ccbba74be4aedf127 Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Mon, 1 Jul 2019 15:54:02 +0200 Subject: [PATCH 17/19] grammar --- docs/qs.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/qs.md b/docs/qs.md index cea4622..c451a47 100644 --- a/docs/qs.md +++ b/docs/qs.md @@ -10,4 +10,5 @@ Some information on how we aim to ensure certain level of quality. ## XML-Security Best Practices -* We follow the [OWASP recommendations](https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/XML_Security_Cheat_Sheet.md) on best practices for JAVA XML to mitigate XML eXternal Entity (XXE) attacks and per default we do not allow external references on Entities and XIncludes \ No newline at end of file +* We follow the [OWASP recommendations](https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/XML_Security_Cheat_Sheet.md) + on best practices for JAVA XML to mitigate XML eXternal Entity (XXE) attacks and we do not allow external references on Entities and XIncludes per default. From 4de317ccb8cf0e45e5ff212235e1e6d69b22fc50 Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Mon, 1 Jul 2019 16:14:24 +0200 Subject: [PATCH 18/19] =?UTF-8?q?Add=20Engl.=20name=20of=20Pr=C3=BCftool?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/about.md b/docs/about.md index 6e2eefa..ee2760e 100644 --- a/docs/about.md +++ b/docs/about.md @@ -2,4 +2,4 @@ ## German -In seiner 23. Sitzung hat der [IT-Planungsrat](https://www.it-planungsrat.de) mit [Beschluss 2017/22 (6a)](https://www.it-planungsrat.de/SharedDocs/Sitzungen/DE/2017/Sitzung_23.html?pos=3) die [Koordinierungsstelle für IT-Standards (KoSIT)](https://www.xoev.de/) im Rahmen des Betriebs des Standards XRechnung mit der dauerhaften„…Bereitstellung eines Moduls zur Konformitätsprüfung elektronischer Rechnungen als offene Referenzimplementierung sowie …“ aller zugehöriger Artefakte beauftragt. Im Rahmen dieser Beauftragung wurde die hier bereitgestellte Software "Prüftool" entwickelt und (vor-) konfiguriert. +In seiner 23. Sitzung hat der [IT-Planungsrat](https://www.it-planungsrat.de) mit [Beschluss 2017/22 (6a)](https://www.it-planungsrat.de/SharedDocs/Sitzungen/DE/2017/Sitzung_23.html?pos=3) die [Koordinierungsstelle für IT-Standards (KoSIT)](https://www.xoev.de/) im Rahmen des Betriebs des Standards XRechnung mit der dauerhaften„…Bereitstellung eines Moduls zur Konformitätsprüfung elektronischer Rechnungen als offene Referenzimplementierung sowie …“ aller zugehöriger Artefakte beauftragt. Im Rahmen dieser Beauftragung wurde die hier bereitgestellte Software "Prüftool" (Engl. Validator) entwickelt und (vor-) konfiguriert. From 41d3fba7fb631772b27c5c8e2633f207cce01384 Mon Sep 17 00:00:00 2001 From: Renzo Kottmann Date: Mon, 1 Jul 2019 16:14:55 +0200 Subject: [PATCH 19/19] Better match of diagram wording with description --- docs/architecture.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 11ef1ed..fc9b2a2 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,7 +2,7 @@ The validator itself is just an engine which executes validation according to a certain configuration (see [configuration documentation](docs/configurations.md)). -The validator takes a sceanrio.xml and the configured directory with all artifacts necessary for validation (scenario repository). Then it performs +The validator takes a scenario.xml and the configured directory with all artifacts necessary for validation (scenario repository). Then it performs the validation and generates a report in XML format. This report is then the input to an XSLT provided by the configuration. ## Separation of concerns @@ -13,9 +13,9 @@ the validation and generates a report in XML format. This report is then the inp The validator reports valid/invalid, a configuration reports acceptance/rejection! - ## General process -The general process is like this: + +The general process is like this: ```mermaid @@ -30,15 +30,23 @@ sequenceDiagram e->>e: validate Schematron e->>e: create Validator Report e->>+c: execute configuration report generator - c->>-e: return XPATH of acceptance message - + ``` - -1. *XML-Parsing*: Is the XML instance valid in the basic sense. If not, validation is stopped and the validator report is returned with status *invalid*. -2. *Identifikation of applicable scenario*: The configuration must have a defined scenario which matches the XML instance (it is an XPATH expression). If no scenario matches, validation is stopped and the validator report is returned with status *invalid*. -3. *XML-Schema validation*: The XML instance must be valid according to the configured XSD. If not, validation is stopped and the validator report is returned with status *invalid*. -4. *Schematron validation* -5. *Aggregation of validation results*: All results are aggregated into the validation report: - * In case there is a single *error* or *warning* the report will have status erhält*invalid*, otherwise the status will be *valid*. +1. *parse XML*: + Is the XML instance valid in the basic sense. If not, validation is stopped and the validator report is returned with status *invalid*. +2. *select scenario*: + + The configuration must have a defined scenario which matches the XML instance (it is an XPATH expression). If no scenario matches, validation is stopped and the validator report is returned with status *invalid*. +3. *validate XML-Schema*: + + The XML instance must be valid according to the configured XSD. If not, validation is stopped and the validator report is returned with status *invalid*. +4. *validate Schematron* +5. *create Validator Report*: + + All results are aggregated into the validation report: + * Depending on the configuration in the scenario, if there is a single *error* or *warning* the report will have status *invalid*, otherwise the status will be *valid*. +6. *execute configuration report generator* + + The Validator will search for the XSLT as configured in scenario.xml and execute it with the Validator Report as input