Gematik Referenzvalidator

Inhaltsverzeichnis

1. Über das Projekt
   • Release Notes
2. Funktionsumfang
   • Unterstützte Validierungsmodule
   • E-Rezept-Modul
   • EAU-Modul
   • Code-Modul
   • E-Rezept Abrechnungsdaten-Modul (EXPERIMENTELL)
   • Externe Validierungsmodule (Plugins)
3. Erste Schritte
   • Voraussetzungen
   • Installation
4. Verwendung
5. Lizenz
6. Beiträge zum Projekt und Danksagung
7. Kontakt

Über das Projekt

Der Referenzvalidator ermöglicht eine erweiterte Validierung von FHIR-Ressourcen, die in den Anwendungen der Telematikinfrastruktur (TI) verwendet werden. Der Referenzvalidator liefert autoritative Antworten zur Validität von übertragenen Datensätzen und ist somit eine Referenz für eventuell sonst im Rahmen einer TI-Anwendung eingesetzte FHIR-Validatoren.

Siehe Use Cases, Anforderungen, Architektur, Entwicklungsprozess für weitere Informationen.

Warning Die Verbindlichkeit des E-Rezept-Moduls vom Referenzvalidator in Abrechnungsprozessen wird in der Technische Anlage 7, Anhang 2, zur Arzneimittelabrechnungsvereinbarung gemäß § 300 Absatz 3 SGB V festgelegt. Siehe auch E-Rezept: Technische Verarbeitbarkeit, Schiedsrichter-Rolle und Problemlösungsverfahren. Die Verbindlichkeit anderer Validierungsmodule wurde bisher nicht festgelegt. Es besteht lediglich eine Nutzungsempfehlung seitens der gematik.

Warning Der Betrieb des Referenzvalidators in bestehenden Anwendungen oder Anwendungslandschaften obliegt der Verantwortung der Nutzer. Die gematik trifft angemessene Maßnahmen, um die Sicherheit und Performance des Referenzvalidators zu gewährleisten. Sie übernimmt aber keine Verantwortung für etwaige Schäden, die durch die Integration des Referenzvalidators in Produktionssysteme entstehen (siehe auch Haftungsausschuss der Apache 2.0-Lizenz. Insbesondere müssen die Sicherheitsaspekte des Gesamtsystems unter Einbeziehung der technischen und organisatorischen Rahmenbedingungen der jeweiligen Betriebsumgebung durch die Nutzer selbst bewertet werden. Des Weiteren hängen die Performance-Eigenschaften des Validators stark von der jeweiligen Betriebsumgebung ab.

Release Notes

Siehe Release Notes

Funktionsumfang

• Validierung von FHIR-Ressourcen anhand der referenzierten Profile
• Der Prüfumfang entspricht dem Umfang des HL7 Java Validators:
  • Struktur: Alle Elemente einer Instanz MÜSSEN in dem referenzierten Profil definiert sein
  • Kardinalität: Die Min/Max-Angaben aller Eigenschaften sind berücksichtigt
  • Wertebereiche: Die Wertebereiche von Eigenschaften werden berücksichtigt (einschließlich aufgelistete Codes)
  • Coding/CodeableConcept bindings: Die Code-Angaben in einer Instanz entsprechen der Definition des Kodierungssystems aus dem Profil
  • Constraints/Invariants: Die für die Eigenschaften im Profil definierten Regeln sind eingehalten
• Prüfung der Gültigkeitszeiträume der in den Instanzen referenzierten Profile
• Nutzung der FHIR-Package-Abhängigkeiten in Abhängigkeit von dem Instanz-Erstellungszeitpunkt (bspw. der datumsabhängigen KBV-Schlüsseltabellen)

Unterstützte Validierungsmodule

Modul	Version
E-Rezept	2.11
Elektronische Arbeitsunfähigkeitsbescheinigung	1.0
FHIR Core	1.0
E-Rezept Abrechnungsdaten (experimentell)	0.3

E-Rezept-Modul

Abweichend vom allgemeinen Prüfumfang verhält sich das E-Rezept-Modul wie folgt:

• Folgende CodeSysteme werden nicht validiert:
  • http://fhir.de/CodeSystem/ifa/pzn
  • http://fhir.de/CodeSystem/ask
  • http://fhir.de/CodeSystem/bfarm/atc (wird in GEM_ERP_PR_Medication verwendet)
  • http://snomed.info/sct (wird in GEM_ERP_PR_Medication verwendet)
  • https://terminologieserver.bfarm.de/fhir/CodeSystem/arzneimittel-referenzdaten-pharmazeutisches-produkt (wird in GEM_ERP_PR_Medication verwendet)
• Folgende CodeSysteme werden validiert, führt aber zu einer Warnung im Falle der Nicht-Validität:
  • http://unitsofmeasure.org
• Folgende ValueSets werden nicht validiert:
  • http://hl7.org/fhir/uv/ips/ValueSet/medicine-doseform (wird in GEM_ERP_PR_Medication verwendet)
• Fehler, die bei Validierung von http://fhir.abda.de/eRezeptAbgabedaten/StructureDefinition/DAV-PR-ERP-AbgabedatenBundle|1.0.3 im Zusammenhang mit falschen Angaben bei http://fhir.abda.de/Identifier/DAV-Herstellerschluessel stehen, werden ignoriert und führen zum validen Ergebnis
• Instanzen mit unbekannten Profilen führen zum invaliden Ergebnis
• Instanzen mit unbekannten Extensions führen zum invaliden Ergebnis
• Alle E-Rezept-Ressourcen (auch verschachtelte) dürfen nur genau eine meta.profile-Angabe enthalten (obwohl manche Profile technisch auch mehrfache meta.profile-Angaben erlauben).

Warning Das E-Rezept-Modul validiert nur FHIR-Instanzen, für die ein Profil im Rahmen der jeweiligen FHIR-Spezifikationen definiert wurde. Manche Ausgaben vom E-Rezept-Fachdienst (z.B. collection-Bundles), für die kein dediziertes Profil definiert wurde, sind nicht Bestandteil des Prüfumfangs. Diese Instanzen sind daher nicht validierbar.

Anpassungen der Packages:

• Alle Packages enthalten Snapshots

Anpassungen der Profile

• de.gematik.erezept-workflow.r4-1.0.3-1.tgz
  • ErxChargeItem.json
    • BugFix: Korrektur der supportiveInformation-Slices (Keine Snapshot-Generierung sonst möglich)
• de.gematik.erezept-workflow.r4-1.1.1.tgz
  • ErxCommunicationReply.json
    • Communication.about targetProfile: typos: KBV_PR_ERP_Medikament_Freitext, KBV_PR_ERP_Medikament_PZN, KBV_PR_ERP_Medikament_Rezeptur, erxTask. Korrigiert in KBV_PR_ERP_Medication_FreeText, KBV_PR_ERP_Medication_PZN, KBV_PR_ERP_Medication_Compounding, ErxTask
• de.abda.erezeptabgabedatenbasis-1.1.0.tgz
  • Extension-DAV-EX-ERP-Rezeptaenderung.json
  • Extension-DAV-EX-ERP-Zusatzattribute.json
  • Extension-DAV-EX-ERP-ZusatzdatenHerstellung.json
    • Änderungen siehe Version 0.9.6 im ChangeLog.md des ABDA Referenzvalidators

EAU-Modul

Abweichend vom allgemeinen Prüfumfang verhält sich das eAU-Modul wie folgt:

• ICD-10-Codes (CodeSysteme http://fhir.de/CodeSystem/dimdi/icd-10-gm und http://fhir.de/CodeSystem/bfarm/icd-10-gm) werden nicht validiert
• Instanzen mit unbekannten Profilen führen zum invaliden Ergebnis
• Instanzen mit unbekannten Extensions führen zum invaliden Ergebnis

Für folgende Profile erfolgen Instanz-datumsbasierte Auswahl der FHIR-Packages zur Validierung sowie Profilgültigkeitsprüfungen:

Profil	Datenelement	Anmerkung
KBV_PR_EAU_Bundle	Bundle.entry.resource.where(meta.profile.contains('KBV_PR_EAU_Composition')).date	Ausstellungsdatum
KBV_PR_EAU_Composition	date	Ausstellungsdatum
KBV_PR_EAU_Storno_Bundle	Bundle.entry.resource.where(meta.profile.contains('KBV_PR_EAU_Composition')).date	Aktuelles Datum der Stornierung
KBV_PR_EAU_Storno_Composition	date	Aktuelles Datum der Stornierung

Anpassungen der Packages:

• Alle Packages enthalten Snapshots

Anpassungen der Profile

• de.basisprofil.r4-0.9.13.tgz
  • Extension-seitenlokalisation.json
    • BugFix: Version 0.9.12 auf 0.9.13 korrigiert

CORE-Modul

Der Referenzvalidator bietet die Möglichkeit, FHIR Core-Ressourcen zu validieren. Beim Aufruf des core-Validierungsmoduls ist die Angabe einer Profil-Canonical-URL zur Validierung erforderlich (siehe Optionen der Konsolenanwendung).

E-Rezept Abrechnungsdaten-Modul (EXPERIMENTELL)

Dieses Modul bietet eine experimentelle Umsetzung zur performanten Validierung von großen TA7-FHIR-Abrechnungsdateien. Unterstützt werden nur Resourcen mit dem Profil https://fhir.gkvsv.de/StructureDefinition/GKVSV_PR_TA7_Rechnung_Bundle|1.3.0.

Das Modul mit der id erpta7 kann auf die gleiche Art und Weise verwendet werden wie das E-Rezept-Modul, z.B.

java -jar .\referencevalidator-cli-X.Y.Z.jar erpta7 c:\temp\big-ta7-file.xml

oder aus dem Quellcode heraus unter der Verwendung der entsprechenden Kennung SupportedValidationModule.ERPTA7:

ValidationModule erpModule = new ValidationModuleFactory().createValidationModule(SupportedValidationModule.ERPTA7);

Für die Validierung der TA7-FHIR-Instanzen teilt das Modul die Eingabe in mehrere GKVSV_PR_TA7_RezeptBundle-Ressourcen auf und validiert diese unabhängig voneinander - parallel und unter Verwendung des E.Rezept-Validierungsmoduls. Zusätzlich erfolgt Validierung des umschließenden Bundles, anderer Ressourcen sowie Querverweisprüfungen innerhalb der Eingabe-FHIR-Instanz, um die Gesamtkorrektheit der Validierung zu gewährleisten. Das Modul strebt identische Validierungsergebnisse wie das E-Rezept-Modul an. Die Leistung des Moduls hängt von der Anzahl der verfügbaren CPU-Kerne ab, was der Anzahl der vom Modul gestarteten parallelen Threads entspricht. Wie auch das E-Rezept-Modul validiert das ERPTA7-Modul KEINE base64-kodierten Daten (eRezepte, Abgabedaten, Belege) innerhalb der TA7-Datei.

Externe Validierungsmodule (Plugins)

Der Referenzvalidator kann mit weiteren Validierungsmodulen erweitert werden. Die von der gematik bereitgestellten Validierungsmodule können aus dem entsprechenden GitHub-Repository heruntergeladen werden.

Nutzung mit der Konsolenanwendung

Die Plugins sollen im Ordner plugins auf derselben Ordnerebene wie die jar-Referenzvalidator-Datei abgelegt werden. Beim Aufruf des Referenzvalidators soll die id des abgelegten Plugins angegeben werden.

Beispiel der Ordnerstruktur:

referencevalidator/
├── plugins/
│   └── isik3-terminplanung.zip
├── referencevalidator-cli-X.Y.Z.jar
└── test-ISIKTermin.json

Beispielaufruf:

    cd referencevalidator
    java -jar .\referencevalidator-cli-X.Y.Z.jar isik3-terminplanung test-ISIKTermin.json

Nutzung mit der Java-Bibliothek

Plugin plugin = Plugin.createFromZipFile(new ZipFile("src/test/resources/plugins/minimal-plugin.zip"));
var pluginModule = new ValidationModuleFactory().createValidationModuleFromPlugin(plugin);
String fhirRessource = "<Bundle xmlns=\"http://hl7.org/fhir\">\n"
        + "    <id value=\"fb16b9fb-eca9-4a64-b257-083ac87c9c9c\"/>\n"
        + "    <meta>\n"
        + "        <profile value=\"https://fhir.kbv.de/StructureDefinition/KBV_PR_ERP_Bundle|1.0.1\"/>\n"
        + "        \n"
        + "    </meta>\n"
        + "</Bundle>";
var result = pluginModule.validateString(fhirRessource);
System.out.println(result.isValid());

Erste Schritte

Voraussetzungen

Der Referenzvalidator wird als Java-Bibliothek und als Konsolenanwendung verteilt. Für die Verwendung ist JDK 11 erforderlich (z.B. AdoptOpenJDK).

Warning Der Referenzvalidator verfolgt das Ziel, die Validierungsergebnisse unabhängig von den lokalen Einstellungen der Zeitzone oder der Zahlendarstellung zu produzieren. Bei den lokalen Spracheinstellungen ist allerdings darauf zu achten, dass Deutsch oder Englisch als Sprache voreingestellt ist (z.B. Locale de_DE oder en_US). Bei anderen Sprachen kann es in Randfällen zur Abweichung bei der Bewertung der Validität der Instanzen kommen.

Installation

Konsolenanwendung

Für die Verwendung der Konsolenanwendung soll die Datei referencevalidator-cli-X.Y.Z.jar in einem beliebigen Ordner im Dateisystem abgelegt werden (siehe Releases).

Java-Bibliothek

Der Referenzvalidator wird zur Einbindung in andere Projekte auf Maven Central veröffentlicht.

Warning Bei der Einbindung ist darauf zu achten, dass genau die angegebenen Versionen der Abhängigkeiten, insbesondere der HAPI-Bibliothekten (ca.uhn.hapi.fhir), zur Laufzeit eingebunden sind. Im Falle der Abweichung können die Validierungsergebnisse anders ausfallen als erwartet.

Beispiel zur Einbindung des Referenzvalidator:

    <dependency>
          <groupId>de.gematik.refv</groupId>
          <artifactId>referencevalidator-lib</artifactId>
          <version>${version.referencevalidator}</version>
    </dependency>

Die Versionsangabe ${version.referencevalidator} soll mit der gewünschten einzubindenden Referenzvalidator-Version ersetzt werden.

Verwendung

Konsolenanwendung

Der Referenzvalidator erfordert als Eingabe einen Modulnamen und einen oder mehrere gültige Pfade zu Dateien oder Verzeichnissen, die FHIR-Ressourcen enthalten (bei mehreren Pfaden müssen diese mit Kommas separiert werden):

java -jar referencevalidator-cli-X.Y.Z.jar erp c:\temp\example.xml
java -jar referencevalidator-cli-X.Y.Z.jar erp c:\temp\example.xml,c:\temp\example2.xml,c:\temp\folder-with-fhir-resources

Unterstützte Modulnamen:

• erp (E-Rezept)
• eau (Elektronische Arbeitsunfähigkeitsbescheinigung)
• core (FHIR Core)
• erpta7 (E-Rezept Abrechnungsdaten)

Optionen:

• --verbose - Verbode-Modus mit Debug-Protokoll-Ausgaben und INFORMATION- bzw. WARNING-Validierungsnachrichten
• --no-profile-validity-period-check - Deaktivierung der Zeitraumgültigkeitsprüfung der Profilversionen
• --profile - Angabe einer Profil-Canonical-URL zur Validierung. Falls angegeben, wird die Angabe der Instanz unter meta.profile ignoriert
• --profile-filter - Angabe eines regulären Ausdrucks zur Prüfung der unter meta.profile referenzierten Profile. Falls kein referenzierstes Profil dem regulären Ausdruck entspricht, wird die Instanz als invalide betrachtet. Beispiele zur Nutzung:
  • Prüfen, dass es sich bei einer Instanz grundsätzlich um eine E-Rezept-Quittung und nicht etwa um eine Verordnung handelt: --profile-filter "ErxReceipt|GEM_ERP_PR_Bundle"
  • Prüfen, dass es sich bei einer Instanz um eine E-Rezept-Verordnung (in der Profilversion 1.1) handelt: --profile-filter "KBV_PR_ERP_Bundle\|1\.1"
  • Prüfen, dass es sich bei einer Instanz um Abgabedaten (GKV oder PKV) handelt: --profile-filter "DAV-(PKV-)?PR-ERP-AbgabedatenBundle"
• --module-info - Ausgabe der unterstützten Profile, Profilversionen und FHIR-Packages zu einem Validierungsmodul
• --accepted-encodings - Komma-separierte Liste mit den zu akzeptierenden Serialisierungsformaten der FHIR-Ressourcen. Unterstützte Werte: xml,json. Überschreibt die Modul-eigene Konfiguration.
• --output - Angabe eines Dateipfades um das Validierungsergebnis in Form einer FHIR OperationOutcome-Ressource bzw. eines Bundles mit OperationOutcome-Ressourcen in eine Datei zu schreiben. Beispiel: --output c:\temp\output.xml. Als Ausgabeformate werden sowohl xml als auch json unterstützt. Die Struktur der Ausgabedateien ist in der weiterführenden Dokumentation zu finden.

Java-Bibliothek

Folgende Beispiele veranschaulichen die Verwendung vom Referenzvalidator in einer Java-Anwendung.

Validierung einer FHIR-Ressource aus einer Datei:

        ValidationModule erpModule = new ValidationModuleFactory().createValidationModule(SupportedValidationModule.ERP);
        ValidationResult result = erpModule.validateFile("c:/temp/KBV_PR_ERP_Bundle.xml");
        System.out.println(result.isValid());
        System.out.println(result.getValidationMessages());

Validierung einer FHIR-Ressource als String:

    ValidationModule erpModule = new ValidationModuleFactory().createValidationModule(SupportedValidationModule.ERP);
    String fhirRessource = "<Bundle xmlns=\"http://hl7.org/fhir\">\n"
        + "    <id value=\"fb16b9fb-eca9-4a64-b257-083ac87c9c9c\"/>\n"
        + "    <meta>\n"
        + "        <profile value=\"https://fhir.kbv.de/StructureDefinition/KBV_PR_ERP_Bundle|1.0.1\"/>\n"
        + "        \n"
        + "    </meta>\n"
        + "</Bundle>";
    ValidationResult result = erpModule.validateString(fhirRessource);
    System.out.println(result.isValid());
    System.out.println(result.getValidationMessages());

Die Validierungseinstellungen können auch angepasst werden:

        ValidationModule erpModule = new ValidationModuleFactory().createValidationModule(SupportedValidationModule.ERP);
        ValidationOptions options = ValidationOptions.getDefaults();
        options.setProfileValidityPeriodCheckStrategy(ProfileValidityPeriodCheckStrategy.IGNORE);
        options.setProfiles(List.of("https://fhir.kbv.de/StructureDefinition/KBV_PR_ERP_Bundle|1.0.1"));
        options.setAcceptedEncodings(List.of("xml", "json"));
        options.setValidationMessagesFilter(ValidationMessagesFilter.KEEP_ALL);
        options.setProfileFilterRegex("KBV_PR_ERP_Bundle");
        ValidationResult result = erpModule.validateFile("c:/temp/KBV_PR_ERP_Bundle.xml", options);
        System.out.println(result.isValid());
        System.out.println(result.getValidationMessages());

Die Anpassung der Validierungseinstellungen soll allerdings nur für Testzwecke erfolgen, da damit die Bewertung der eingegebenen Instanz gegenüber Standardeinstellungen verfälscht wird.

License

Copyright 2025 gematik GmbH

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.

See the LICENSE for the specific language governing permissions and limitations under the License.

Additional Notes and Disclaimer from gematik GmbH

1. Copyright notice: Each published work result is accompanied by an explicit statement of the license conditions for use. These are regularly typical conditions in connection with open source or free software. Programs described/provided/linked here are free software, unless otherwise stated.
2. Permission notice: Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
3. The copyright notice (Item 1) and the permission notice (Item 2) shall be included in all copies or substantial portions of the Software.
4. The software is provided "as is" without warranty of any kind, either express or implied, including, but not limited to, the warranties of fitness for a particular purpose, merchantability, and/or non-infringement. The authors or copyright holders shall not be liable in any manner whatsoever for any damages or other claims arising from, out of or in connection with the software or the use or other dealings with the software, whether in an action of contract, tort, or otherwise.
5. The software is the result of research and development activities, therefore without the character of a liable product.
6. Gematik may remove published results temporarily or permanently from the place of publication at any time without prior notice or justification.
7. Please note: Parts of this code may have been generated using AI-supported technology.’ Please take this into account, especially when troubleshooting, for security analyses and possible adjustments.

Beiträge zum Projekt und Danksagung

Teile des Projekts basieren auf dem ABDA E-Rezept-Referenzvalidator (Copyright 2022 Deutscher Apothekerverband (DAV)), der unter Apache License, Version 2.0 steht. Modifizierte Quellcodedateien sind im Quellcode als solche gekennzeichnet.

Die Snapshots für die FHIR-Packages wurden auf Basis vom Pull Request von spectrumK und bakdata vorgeneriert und in den Referenzvalidator eingebunden.

Kontakt

Fragen, Anregungen, Bug Reports und Feature requests sind willkommen und können gerne über die GitHub Issues oder über referenzvalidator@gematik.de eingereicht werden.