Wie man ein FHIR Questionnaire versioniert

In diesem Artikel untersuchen wir, wie die Versionierung von FHIR Questionnaires funktioniert und warum sie für die Wahrung der Datenintegrität unerlässlich ist. Wir erläutern die kanonische Versionierung in FHIR, erörtern gängige Versionierungsansätze, erklären den Umgang mit verschiedenen Änderungstypen mithilfe von Semantic Versioning und heben praktische Empfehlungen sowie häufige Fehler hervor. Ziel ist es, klare Orientierung für die Weiterentwicklung von Questionnaires zu geben, ohne die Kompatibilität zu brechen.

Einleitung

In FHIR ist ein Questionnaire eine kanonische Ressource, die strukturierte Formulare zur Erfassung von Gesundheitsdaten beschreibt. Es definiert eine Liste von Fragen, deren Gruppierung und Reihenfolge, Antwortoptionen sowie komplexeres dynamisches Verhalten auf Grundlage bereits gegebener Antworten. Im Laufe der Zeit ändern sich Formulare: Neue Fragen werden hinzugefügt, Formulierungen werden präzisiert, die Struktur wird umorganisiert und veraltete Elemente werden entfernt.

Diese Änderungen sind unvermeidlich, stellen jedoch eine kritische Herausforderung dar: Wie lässt sich sicherstellen, dass zuvor erfasste QuestionnaireResponse-Daten korrekt und interpretierbar bleiben?

Da Questionnaire eine kanonische Ressource ist, unterliegt sie den kanonischen Versionierungsregeln. Durch die Versionierung können Sie das zur Datenerfassung verwendete Formular eindeutig identifizieren, die korrekte Interpretation von Antworten sicherstellen, eine Prüfhistorie führen und Verbesserungen sicher einführen, ohne die Kompatibilität zu gefährden. Ohne ordnungsgemäße Versionierung können bereits kleine strukturelle Änderungen historische Daten unzuverlässig machen.

Kanonische Versionierung in FHIR

Kanonische Ressourcen in FHIR (wie Questionnaire, StructureDefinition, ValueSet, CodeSystem) sind wiederverwendbar, stabil und versioniert. Sie werden durch eine global eindeutige url und eine version identifiziert.

Ein minimales Beispiel:

{
  "resourceType": "Questionnaire",
  "url": "http://aidbox.app/fhir/Questionnaire/vitals-form",
  "version": "1.0.0",
  "status": "active"
}

Die url ist ein dauerhafter logischer Bezeichner und muss über alle Versionen hinweg unverändert bleiben. Die version identifiziert eine bestimmte Ausgabe des Formulars und ändert sich, sobald das Formular auf bedeutungsvolle Weise geändert wird. Der status (draft, active, retired, unknown) spiegelt den Lebenszyklusstatus wider, nicht die Versionierung selbst.

Wenn ein Questionnaire ausgefüllt wird, sollte die QuestionnaireResponse auf die genaue verwendete Version verweisen:

"questionnaire":
 "http://aidbox.app/fhir/Questionnaire/vitals-form|1.0.0"

Diese Referenz gewährleistet die korrekte Interpretation der Daten, auch wenn später neuere Versionen eingeführt werden. Jede neue Version ist im Grunde eine neue Ressource. Bereits veröffentlichte Versionen müssen unveränderlich bleiben. Mehrere Versionen können gleichzeitig im System coexistieren – dies ist grundlegend für Abwärtskompatibilität und regulatorische Compliance.

Versionierungsansätze

FHIR legt nicht strikt fest, wie Versionsnummern strukturiert sein müssen. Ab FHIR R5 kann das optionale Element versionAlgorithm den gewählten Ansatz (semantisch, numerisch, datumsbasiert usw.) angeben, ist jedoch nicht verpflichtend.

Der am weitesten verbreitete und empfohlene Ansatz ist Semantic Versioning (SemVer) im Format MAJOR.MINOR.PATCH (beispielsweise 2.1.0). In diesem Modell gilt:

• MAJOR kennzeichnet breaking Changes, die die Kompatibilität beeinträchtigen (Entfernen von Fragen, Ändern von linkId, Umstrukturierung des Formulars).

• MINOR kennzeichnet abwärtskompatible Ergänzungen (Hinzufügen von Fragen, Erweiterung von Antwortoptionen).

• PATCH kennzeichnet nicht brechende Korrekturen (Tippfehler, Präzisierung von Formulierungen ohne Bedeutungsänderung).

Semantic Versioning macht Kompatibilität explizit und hilft Implementierern zu entscheiden, ob ein Upgrade sicher ist.

Weitere Ansätze umfassen datumsbasierte Versionierung (z. B. 2025-08 oder 2025.08.15), die den Veröffentlichungszeitpunkt klar ausweist, jedoch keine Kompatibilitätsaussage trifft, sowie einfache inkrementelle oder alphanumerische Schemata (1, 2, 3 oder rev1, rev2), die flexibel sind, aber semantische Klarheit vermissen lassen.

Unabhängig von der gewählten Methode ist es wichtig, einen einheitlichen Ansatz pro Formular (gleiche url) zu verwenden und sicherzustellen, dass jedes (url, version)-Paar eindeutig ist.

Typische Änderungsszenarien und SemVer-Versionierung

Bei der Änderung eines Questionnaires lautet die entscheidende Frage, ob die Änderung die Struktur oder Interpretation der gesammelten Daten beeinflusst. Die Antwort bestimmt die erforderliche Versionserhöhung.

Betrachten wir die folgenden Änderungstypen:

• Frage hinzufügen
• Frage entfernen
• linkId ändern
• Code ändern
• Text ändern
• Fragereihenfolge ändern
• Gruppenstruktur ändern
• Ausfülllogik ändern

Fragen hinzufügen

Das Hinzufügen einer neuen Frage ohne Änderung bestehender Fragen ist eine abwärtskompatible Änderung und sollte die Minor-Version erhöhen (1.1.0 → 1.2.0).

Fragen entfernen

Das Entfernen einer Frage ist eine breaking Change und erfordert eine Erhöhung der Major-Version (1.1.0 → 2.0.0).

linkId ändern

Das Ändern von linkId bricht die Bindung zwischen Questionnaire-Elementen und QuestionnaireResponse-Antworten und muss daher stets als Major-Änderung behandelt werden (1.1.0 → 2.0.0).

Codes ändern (code)

Das Aktualisieren oder Ersetzen von Codes, die zur semantischen Identifikation von Fragen verwendet werden (z. B. LOINC, SNOMED CT), kann die klinische Bedeutung einer Frage verändern und die Interoperabilität beeinflussen. Die Auswirkung hängt jedoch von der Art der Änderung ab:

• Wird ein Code vollständig durch einen anderen ersetzt, handelt es sich um eine breaking Change, die eine Erhöhung der Major-Version erfordert (1.1.0 → 2.0.0).
• Wird ein zusätzlicher Code hinzugefügt, ohne den alten zu entfernen, handelt es sich um eine Minor-Versionserhöhung (1.1.0 → 1.1.1).

Fragetext ändern

Das Anpassen von Formulierungen, die Übersetzung in eine andere Sprache oder die Korrektur von Grammatikfehlern kann verschiedenen Änderungstypen entsprechen, je nachdem, ob sich die Bedeutung ändert:

• Ändert sich die Bedeutung nicht, handelt es sich um ein Patch-Update (1.1.0 → 1.1.1).
• Ändert sich die Bedeutung, handelt es sich um ein Major-Update (1.1.0 → 2.0.0).

Fragereihenfolge ändern

Das Umordnen von Elementen innerhalb derselben Verschachtelungsebene beeinflusst die Interpretation in der Regel nicht, kann jedoch die Benutzerführung und den Ausfüllablauf verändern. Dies ist eine Minor-Versionsänderung (1.1.0 → 1.1.1).

Gruppenstruktur ändern

Das Verschieben von Fragen zwischen Gruppen oder das Ändern der Verschachtelung kann die Zuordnung von Antworten beeinflussen und enableWhen-Regeln brechen (z. B. eine Frage, die sich zuvor in einer standardmäßig ausgeblendeten Gruppe befand) – was zu unvorhersehbaren Ergebnissen führt. Solche Änderungen sollten als Major-Versionsupdate behandelt werden (1.1.0 → 2.0.0).

Ausfülllogik ändern

Bearbeitungen in enableWhen, required, maxLength und anderen Regeln können beeinflussen, welche Antworten erfasst werden.

• Handelt es sich um geringfügige Anpassungen, ist es ein Minor-Versionsupdate.
• Ändern sich die Bedingungen wesentlich, ist es ein Major-Versionsupdate.

Praktische Empfehlungen und Best Practices

Eine ordnungsgemäße Versionierung eines Questionnaires minimiert das Risiko von Kompatibilitätsbrüchen und vereinfacht die Formularpflege. Nachfolgend finden Sie Empfehlungen aus der Erfahrung mit der Implementierung von FHIR in klinischen Systemen.

Veröffentlichte Versionen nicht ändern

Sobald ein Questionnaire mit dem Status active veröffentlicht wurde, muss sein Inhalt unverändert bleiben. Jede Änderung – selbst eine Tippfehlerkorrektur – erfordert die Veröffentlichung einer neuen Version. Historische Versionen müssen unveränderlich bleiben, um die Integrität der Antworten zu wahren.

Eindeutigkeit des (url, version)-Paares sicherstellen

Jede Version eines Formulars muss eine eindeutige Kombination aus url und version aufweisen. Diese Regel ermöglicht die eindeutige Identifikation einer bestimmten Formularausgabe in jedem System. Es wird empfohlen, automatische Eindeutigkeitsprüfungen bei der Veröffentlichung zu implementieren.

Änderungen dokumentieren

Es wird dringend empfohlen, ein Changelog zu führen, das jede Änderung, den Grund dafür und die Einordnung als Major-, Minor- oder Patch-Update dokumentiert. Eine klare Dokumentation vereinfacht die Prüfung und Kompatibilitätsbewertung.

Lebenszyklussteuerung nutzen

Questionnaire-Status

Die Status draft → active → retired sollten den tatsächlichen Zustand des Formulars widerspiegeln.

Verwenden Sie active nicht für Test- oder unvollständige Formulare.

Stellen Sie beim Wechsel eines Formulars in den Status retired sicher, dass es in laufenden Workflows nicht mehr verwendet wird.

Typischer Veröffentlichungsprozess: Entwurf (draft) → Überprüfung → Veröffentlichung (active).

Antworten mit einer bestimmten Version verknüpfen

Geben Sie in QuestionnaireResponse.questionnaire stets eine Referenz im Format {url}|{version} an.

"questionnaire":
 "http://aidbox.app/fhir/Questionnaire/vitals-form|1.1.0"

Dies gewährleistet die korrekte Interpretation der Daten, auch wenn das Formular zukünftig geändert wird.

Prüfungen in den Veröffentlichungsprozess integrieren

Versionsüberprüfungen

Vor der Aktivierung einer neuen Version ist es sinnvoll, die folgenden Prüfungen zu automatisieren:

Sicherstellen, dass keine Duplikate von url + version vorhanden sind.

Überprüfen, ob keine Referenzen auf das Formular in unvollendeten Workflows bestehen, wenn sich die Version ändert.

Diff zwischen Versionen analysieren, um das Ausmaß der Änderungen zu bestimmen.

Kompatibilität im Voraus planen

Auswirkungen von Änderungen

Wenn das Formular voraussichtlich weiterentwickelt wird, verwenden Sie bereits ab der ersten Version stabile linkIds und Codes (code).

Vermeiden Sie abwärtsinkompatible Änderungen, sofern nicht unbedingt erforderlich.

Erwägen Sie den Einsatz von Library-Ressourcen oder separaten Komponenten, um die Auswirkungen von Updates zu reduzieren.

Häufige Fehler bei der Versionierung von Questionnaires

Ein häufiger Fehler ist das Ändern der url anstelle der Erhöhung der Version. Die url muss stabil bleiben, um die Kontinuität zu wahren. Nur die version sollte sich ändern.

Ein weiteres häufiges Problem ist das Ignorieren von Abwärtskompatibilität. Das Entfernen von Fragen oder das Ändern von Bezeichnern ohne Erhöhung der Major-Version kann zur fehlerhaften Interpretation bestehender Antworten führen.

Das Ändern von linkId oder klinischen Codes ohne sorgfältige Überlegung kann das Datenmapping und die Berichterstattung beeinträchtigen. Diese Bezeichner sollten über kompatible Versionen hinweg stabil bleiben.

Die Verwendung inkonsistenter Versionierungsschemata oder informeller Namenskonventionen erschwert die Kompatibilitätsbewertung. Das Mischen von breaking und non-breaking Changes innerhalb derselben Version ohne entsprechende Versionserhöhungen erschwert die Pflege zusätzlich.

Schließlich führt unzureichende Dokumentation zu Unklarheiten darüber, was sich geändert hat und warum, was die langfristige Governance erschwert.

Fazit

Questionnaire-Versionierung

Die Versionierung von FHIR Questionnaire-Ressourcen ist ein zentraler Aspekt der Wahrung von Datenintegrität, der Sicherstellung von Kompatibilität und der Unterstützung der langfristigen Nutzbarkeit klinischer Formulare. Ein ordnungsgemäßes Versionsmanagement bewahrt die Gültigkeit historischer QuestionnaireResponse-Daten und ermöglicht gleichzeitig die Weiterentwicklung von Formularen entsprechend sich ändernder klinischer Anforderungen.

Wesentliche Erkenntnisse:

Konsequente Verwendung von Semantic Versioning (SemVer): Unterscheiden Sie zwischen geringfügigen, abwärtskompatiblen Änderungen und wesentlichen, breaking Changes.

Stabile URLs: Verfolgen Sie Formulare über die Zeit mithilfe einer konstanten url; in der Regel ändert sich nur das version-Element.

Sorgfältige Verwaltung von Elementbezeichnern und Codes: Gewährleistet präzises Mapping und konsistente Berichterstattung über Versionen hinweg.

Dokumentation und Changelog: Unerlässlich, um Entwickler zu informieren und Updates zu unterstützen.

Häufige Fallstricke vermeiden: Kombinieren Sie keine inkompatiblen Änderungen in einer Version und ändern Sie linkId nicht unnötig, um das Fehlerrisiko in klinischen Workflows zu reduzieren.

Letztendlich ermöglicht eine disziplinierte Versionierung Organisationen, Questionnaires sicher weiterzuentwickeln, bei Bedarf Abwärtskompatibilität zu wahren und eine konsistente Datenerhebung und -analyse sicherzustellen. Die Anwendung dieser Grundsätze zusammen mit praktischen Beispielen schafft ein zuverlässiges und wartbares Questionnaire-Ökosystem.

Siehe auch: HL7 FHIR Questionnaires rendern und Wie man einen FHIR Implementation Guide erstellt.