Votum für einen strukturierten, klar dokumentierten Umgang mit Zusatzprüfungen und Black-/Whitelisting

[DarthGizka]

Das Umsetzen von zusätzlichen, über die reine FHIR-Validierung hinausgehenden Prüfungen ist mittlerweile genauso unumgänglich geworden wie das Black- und Whitelisting. Ein hoher Akzeptanzgrad des Validators bei allen Beteiligten läßt sich in dieser Situation nur dann erreichen, wenn alle über die FHIR-Validierung hinausgehenden Zusatzfunktionen klar, übersichtlich und strukturiert dokumentiert und umgesetzt werden.

Zur Verknüpfung der Dokumentation einer Zusatzprüfung oder einer Black-/Whitelisting-Regel mit der entsprechenden Implementierung muß jede Regel einen eindeutigen symbolischen Namen erhalten (e.g. UNBEKANNTE_ERWEITERUNG), der auch als Bezeichner im Quelltext verwendbar ist. Damit könnte dann auch z.B. in Java - und nur dort! ;-) -ein Enum als zentrale Schaltstelle der Implementierung fungieren.

Die Tätigkeit aller Zusatzregeln muß auch im Ergebnis eines Validierungsvorgangs eindeutig erkennbar sein. Derzeit bedeutet z.B. 'Whitelisting', daß irgendwelche Codestückchen einfach Meldungen komplett in die Tonne treten. Die Tätigkeit von Zusatzprüfungen und Blacklisting ist auch nicht wirklich nachvollziehbar.

Daher stelle ich hier das bei uns verwendete System als Vorschlag in den Raum. Es besteht aus drei einfachen Erweiterungen, die an ein OperationOutcome oder an einzelne der darin enthaltenen Meldungen angeheftet werden können.

Ergo eine standardkonforme Erweiterung eines Standardformats, das insbesondere für externe Zwecke (Programmausgabe oder Antwort eines HTTP-APIs) geeignet ist. Programmintern wäre auch die Verwendung von POJO-Strukturen möglich, bis alle Zusatzregeln sich das Validierungsergebnis vorgeknöpft haben (und ggf. Meldungen modifiziert oder eigene Meldungen dazugepackt). Notwendig ist das aber nicht, sofern die R4-Modellform von OperationOutcome intern verwendet wird.

Nachfolgend kommt unsere interne Dokumentation zu den Erweiterungen, und im Anhang gibt es das entspechende Profilpaket(chen).

---

Erweiterungen der Struktur OperationOutcome für den Referenzvalidator

Um das Prüfergebnis maschinell verarbeitbar zur Verfügung stellen zu können, ist es notwendig, einige Erweiterungen für Struktur OperationOutcome zu definieren.

Diese Erweiterungen gliedern sich wie folgt:

• Erweiterungsfeld für die Angabe des Gesamturteils des Validators
• Erweiterungsfeld zur Kennzeichnung von Meldungen, die aus Zusatzprüfungen resultieren
• Zusatzinformationen zur Änderung der Einstufung von Meldungen aufgrund von Black- bzw. Whitelisting

RV_EX_OperationOutcome_Gesamtbewertung

Das Gesamtergebnis der Validierung wird direkt in der Struktur OperationOutcome als Erweiterungsfeld kodiert. Es gibt nur zwei mögliche Werte: 'akzeptiert' und 'fehlerhaft'.

<OperationOutcome xmlns="http://hl7.org/fhir">
    <extension url="https://rz009.de/StructureDefinition/RV-EX-OperationOutcome-Gesamtbewertung">
        <valueCode value="akzeptiert"/>
    </extension>
    <issue>
        <severity value="information"/>
        <code value="informational"/>
        <diagnostics value="No issues detected during validation"/>
    </issue>
</OperationOutcome>

Diese Erweiterung wird nur dann kodiert, wenn der Validator tatsächlich zu einem Ergebnis gekommen ist. Steigt der Validator vorher aus - z.B. aufgrund einer Exception - dann fehlt die Erweiterung. Stattdessen enthält das Feld diagnostics die Meldung der Exception und location enthält den vollständigen Klassennamen; severity ist fatal und code ist processing.

RV_EX_OperationOutcome_Pruefregel

Das Validierungsergebnis kann außer Meldungen aus dem eigentlichen FHIR-Validierungsvorgang auch Meldungen enthalten, die aus zusätzlichen Prüfungen resultieren. Diese Meldungen werden mit dem symbolischen Namen der jeweiligen Zusatzprüfung gekennzeichnet, um eine direkte Zuordnung zur jeweiligen Prüfdefinition zu ermöglichen und um diese zusätzlichen Meldungen von denen des eigentlichen HAPI-Validators unterscheiden zu können.

<OperationOutcome xmlns="http://hl7.org/fhir">
    <issue>
        <extension url="https://rz009.de/StructureDefinition/RV-EX-OperationOutcome-Pruefregel">
            <valueString value="KEINE_RELATIVEN_PSEUDOREFERENZEN_FUER_UUID"/>
        </extension>
        <severity value="error"/>
        <code value="processing"/>
        <diagnostics value="relative Pseudoreferenzen vom Typ Ressourcename + '/' + UUID sind nicht zulaessig"/>
    </issue>
</OperationOutcome>

RV_EX_OperationOutcome_Umstufung

Diese Erweiterung gibt den symbolischen Namen einer Regel zum Black- oder Whitelisting an, die den Schweregrad der betreffenden Meldung herauf- oder heruntergestuft hat.

<OperationOutcome xmlns="http://hl7.org/fhir">
    <issue>
        <extension url="https://rz009.de/StructureDefinition/RV-EX-OperationOutcome-Umstufung">
            <extension url="Umstufungsgrund">
                <valueString value="UNBEKANNTE_ERWEITERUNG"/>
            </extension>
            <extension url="Originalwert">
                <valueCode value="information"/>
            </extension>
        </extension>
        <severity value="error"/>
        <code value="processing"/>
        <diagnostics value="Unknown extension 'https://foo/bar'"/>
    </issue>
</OperationOutcome>

Anmerkung: die als Beispiel angegebenen Umstufung entspricht dem Verhalten des Standard-HAPI-Validators bei Angabe des Schalters -strictExtensions.

de.rz009.rv.zusatz-1.0.0.tar.gz

[DarthGizka]

Das primäre Validierungsergebnis des HAPI-Validators ist ValidationResult. Effektiv handelt es sich dabei aber nur um eine eingewickelte List<SingleValidationMessage>, die über .getMessages() auch extern zugänglich ist.

Die Nachbearbeitung des Validierungsergebnisses teilt sich in Zusatzprüfungen und Black-/Whitelisting.

Ein hypothetisches Modul für Zusatzprüfungen würde die Ressource in einer verarbeitbaren Darreichungsform ausgehändigt bekommen; das Ergebnis wäre eine Liste von Zusatzmeldungen (ggf. leer), von denen jede mit der Id der generierenden Prüfregel gekennzeichnet ist (e.g. Enum).

Ein hypothetisches Modul für Black-/Whitelisting würde die kombinierte Liste aus Validatorergebnis und Zusatzprüfungen vorgelegt bekommen; das Ergebnis der Tätigkeit wäre so etwas wie List<ErweiterteMeldung>:

public class ErweiterteMeldung
{
    public final SingleValidationMessage meldung;
    private ResultSeverityEnum originalSeverity;
    private Umstufungsregel umstufungsgrund;   // Enum
    private Pruefregel pruefregel;   // Enum

    public ErweiterteMeldung (SingleValidationMessage meldung)
    {
        this.meldung = Objects.requireNonNull(meldung);
    }

    public void umstufe_auf (ResultSeverityEnum neuer_schweregrad, Umfstufungsregel umstufungsgrund)
    {
        Objects.requireNonNull(neuer_schweregrad);
        Objects.requireNonNull(umstufungsgrund);

        if (originalSeverity == null)
            originalSeverity = meldung.getSeverity();

        this.umstufungsgrund = umstufungsgrund;
        meldung.setSeverity(neuer_schweregrad);
    }

    // ...
}

Der Einfachheit halber könnte auch das Modul für die Zusatzprüfungen seine Meldungen ebenfalls in diesem Format ausgeben (weniger Reibung/Bürokratie).

Die Verarbeitungspipeline wäre dann

• HAPI-Validator → List<SingleValidationMessage>
• Modul für Zusatzprüfungen → List<ErweiterteMeldung>
• Modul für Black- und Whitelisting ↔ List<ErweiterteMeldung>

Das Ergebnis der Pipeline kann dann entweder direkt angezeigt werden (ggf. mit Unterdrückung von Meldungen geringen Schweregrads) oder in ein OperationOutcome umgewandelt und als XML oder JSON ausgegeben.