Benennung definitorischer Artefakte

Definitorische FHIR-Ressourcen (z.B. StructureDefinition, OperationDefinition, CapabilityStatement, SearchParameter, ValueSet etc) verfügen über harmonisierte Metadaten. Da die korrekte Verwendung dieser Metadaten teilweise Auswirkungen auf das Verhalten und die Stabilität von Tools (z.B. Validatoren) haben kann, empfiehlt sich eine sorgfältige und konsequente Pflege der folgenden Elemente:

id

Die id des Artefaktes sollte stets vorhanden sein und identisch mit name gesetzt werden.

Begründung: Artefakte ohne IDs lösen im Simplifier Quality Control eine Warnung, im IG Publisher einen Fehler aus. Die maximal erlaubte Länge von 64 Zeichen muss beachtet werden.

Tipp: Tools wie SUSHI verwenden name eines Artefaktes um daraus automatisch die id und canonical zu generieren. In diesem Fall muss id nicht manuell gesetzt werden.

url

Oft als "Canonical URL" bezeichnet: Weltweit eindeutiger, technischer Name des Artefaktes. Wird verwendet, um systemübergreifend auf ein Artefakt, unabhängig von dessen Speicherort, Bezug nehmen zu können. Weitere Hinweise siehe

• Bedeutung und Nutzung von Canoncial URLs
• Regeln und Best Practice für die Festlegung von Canonicals

name

Oft als "Computer friendly name" bezeichnet: Muss innerhalb eines Projektes eindeutig sein und einen prägnanten, lesbaren Namen für das Artefakt enthalten. Empfehlenswert ist es, stets der UpperCamelCase-Schreibweise zu folgen. Wenn name und id identisch gewählt werden sollen, muss die für ids maximal erlaubte Länge von 64 Zeichen beachtet werden.

Begründung: Tools wie SUSHI verwenden den Namen eines Artefaktes um daraus automatisch die id und canonical zu generieren. Der name sollte daher unter Berücksichtigung der Konventionen aller dieser Elemente gewählt werden. Eine konsequente CamelCase-Schreibweise erfüllt diese Bedingung.

Tipp: Differenzierung Namen mittels Suffixen
Die Festlegung eines projektweit eindeutigen Namens kann bei manchen Artefakten herausfordernd sein, weil diese semantisch das gleiche ausdrücken, z.B. bei CodeSystem und ValueSet, LogicalModel und Profil, Extension und SearchParameter.

Verhindert werden kann dies - wo sinnvoll und notwendig - beispielsweise durch die Verwendung von Suffixes, z.B.

• ValueSets: VS
• CodeSystems: CS
• Extension: EX
• SearchParameter: SP

Weiter mögliche Suffixe:

• PR: StructureDefinition (Profile)
• EX: StructureDefinition (Extension)
• DT: StructureDefinition (DataType)
• LM: Logical Model
• VS: ValueSet
• CS: CodeSystem
• CM: ConceptMap
• SM: StructureMap
• NS: NamingSystem
• SP: SearchParameter
• CPS: CapabilityStatement
• OD: OperationDefinition
• IG: ImplementationGuide
• EXA: Example

version

Versionsnummer der Ressource in semVer-Syntax. Sollte mit der Versionsnummer der Packages übereinstimmen, in dem das Artefakt publiziert wird.

Begründung: Beim Parallelbetrieb mehrerer Versionen ist es nicht mehr/schwer möglich, das Artefakt einem Package-Kontext zuzuordnen. Eine separate semantisch korrrekte Versionierung jedes einzelnen Artefaktes erhöht darüber hinaus den Pflegeaufwand einer Spezifikation massiv.

Terminologien, die unabhängig von einer Spezifikation weiterentwickelt werden und daher in Ihren Versionen abweichen, sollten in separaten Packages publiziert und als Dependency in eine Spezifikation eingebunden werden.

title

Oft als "Human friendly name" bezeichnet: Unterliegt im Gegensatz zu name keinen Beschränkungen und sollte die bestmögliche Auffindbarkeit des Artefaktes in einer Benutzeroberfläche gewährleisten. Wird in UIs (z.B in Simplifier) anstelle von name zur Anzeige verwendet. Der title sollte Projektweit eindeutig gewählt werden.

Benennung von Packages

package name

Der Package-Name sollte nach folgendem Schema gewählt werden:

[top level domain].[second level domain].[projektname]

z.B.: de.gematik.isik

package version

Version des Packages in SemVer-Syntax: [major].[minor].[patch]

Bedeutung und Nutzung von Canoncial URLs

Canonicals sind weltweit eindeutige Bezeichnungen für Artefakte, mit deren Hilfe in FHIR systemübergreifend, konsistent und interoperabel auf Definitionen verwiesen werden kann.

Diese Bezeichnungen sind unabhängig vom tatsächlichen Speicherort, unter dem diese Definitionen abrufbar sind.

Die Verwechslung von Adressen und Namen kann in FHIR leicht passieren, da es sich i.d.R. bei beidem um URLs handelt. (Canonicals können genau genommen auch andere Formen von URIs annehmen, z.B. OIDs oder UUIDs, üblich und empfohlen sind jedoch URLs. Die Bereitstellung der Artefakte erfolgt i.d.R. über die FHIR-API, welche das HTTP-Protokoll nutzt, wodurch auch der Speicherort als URL gegeben ist.). Speicherort und Name können jedoch verschieden sein. Sie müssen sogar verschieden sein, wenn man bedenkt, dass der Name weltweit eindeutig ist, das entsprechende Artefakt (z.B. ein ValueSet) jedoch auf dutzenden, wenn nicht hunderten verschiedenen FHIR-Servern über eine API (mit jeweils abweichender URL) bereitgestellt werden kann.

Um Artefakte wie z.B. CodeSysteme über die FHIR-API von einer externen Quelle herunterzuladen, braucht man

• die Adresse des FHIR-Endpunktes (z.B. https://terminologieserver.bfarm.de/)
• den Namen des Artefaktes (z.B. http://fhir.de/CodeSystem/bfarm/icd-10)

Die Abfrage des Artefaktes erfolgt dann in der Form einer Suche anhand des Namens (der Canonical-URL) auf dem konfigurierten Endpunkt, z.B.:

https://terminologieserver.bfarm.de/CodeSystem?url=http://fhir.de/CodeSystem/bfarm/icd-10

Der Speicherort der Ressource auf diesem Endpunkt könnte folgendermaßen lauten:

https://terminologieserver.bfarm.de/CodeSystem/[id]

Wobei die [id] von einem Server beliebig gewählt werden kann. Wird das Artefakt anschließend lokal im abrufenden System gespeichert, erhält es eine neue Adresse, z.B.

https://mein-fhir-server.de/fhir/CodeSystem/[id]

Die ID wird dabei von jedem System selbst bestimmt und neu vergeben. Das Artefakt bleibt jedoch auch stets anhand der systemübergreifend stabilen Canonical auffindbar:

https://mein-fhir-server.de/fhir?url=http://fhir.de/CodeSystem/bfarm/icd-10

Wärend sich also die Adresse abhängig von dem bereitstellenden System ändert, bleibt die Canonical über alle Systeme hinweg konstant.

Der Verweis auf Definitionen anhand ihrer Canonical stellt sicher, dass unterschiedliche Systeme verstehen, dass die gleiche Definition gemeint ist, obwohl diese in den Systemen an völlig unterschiedlichen Speicherorten abgelegt sein kann.

Datentyp von Canoncial URLs

Der Datentyp für Canonicals ist URI, was bedeutet, dass zur eindeutigen Benennung einer Definition nicht zwangsläufig eine URL verwendet werden muss. Auch andere Formen von URIs sind erlaubt, z.B. OIDs oder UUIDs.

In der FHIR-Community wird die Verwendung von URLs gegenüber anderen Formen von URIs präferiert, da sie für die Entwickler erhebliche Vorteile haben:

• Sie sind lesbar. Ein Verweis auf die URL http://hl7.org/fhir/ValueSet/data-absent-reason lässt klar erkennen, dass es sich

  • um ein ValueSet handelt,
  • diese von HL7 publiziert wurde und
  • dort Codes zur Begründung von fehlenden Daten enthalten sind.
    Die äquivalente OID “2.16.840.1.113883.4.642.3.5” hingegen lässt keine derlei Rückschlüsse zu.

• Sie sind ubiquitär. Jede Organisation verfügt entweder bereits über eine eigene Domäne oder kann eine solche niederschwellig und kostengünstig registrieren. Für die meisten Organisationen und Projekte sind keine weiteren administrativen Schritte notwendig, um mit der Vergabe von Canonical URLs beginnen zu können. Eine OID müsste hingegen zunächst bei einem Register beantragt werden.

• URLs können nicht nur als Name eines Artefaktes verwendet werden, sondern auch als Adresse, unter der Informationen zu dem jeweiligen Artefakt, bzw. dessen Spezifikation bereitgestellt werden können.

Auflösbarkeit von Canonicals

Zwar besteht weder eine Notwendigkeit noch eine Verpflichtung, dass Canonicals auflösbar sein müssen, es gilt aber dennoch als BestPractice, unter der jeweiligen URL die Spezifikation des Artefaktes verfügbar zu machen, siehe z.B. http://hl7.org/fhir/ValueSet/data-absent-reason

Dies kann mit Hilfe eines Redirects umgesetzt werden, sofern der Name des Artefaktes nicht mit dem Ort der Publikation übereinstimmt.

Beispiel: Die Canonical http://fhir.de/StructureDefinition/seitenlokalisation wird automatisch weitergeleitet auf https://simplifier.net/packages/de.basisprofil.r4/1.5.0-ballot2/files/2367671 wo die aktuelle Spezifikation dieser Extension publiziert ist.

Regeln und Best Practice für die Festlegung von Canonicals

Einzigartigkeit

Canonical URLs sind müssen so gewählt werden, dass sichergestellt ist, dass diese weltweit einzigartig sind. Dies wird dadurch erreicht, dass Organisationen Canonicals aus ihrer Domäne vergeben. Innerhalb einer Domäne ist die zuständige Organisation selbst dafür verantwortlich, die Eindeutigkeit der Vergebenen URLs zu gewährleisten.

Canonicals werden in der Regel vom Autor einer Definition vergeben. Wenn die Canonical jedoch auf eine Definition verweist, die nicht als FHIR-Ressource abgebildet ist (z.B. eine externe Terminologie) und der Autor nicht erreichbar, identifizierbar oder willens ist, eine geeignete Canonical zu bestimmen, dann können Canonicals auch innerhalb der FHIR-Community abgestimmt werden, um dennoch einheitlich und interoperabel auf die jeweiligen Artefakte verweisen zu können. Häufig wird dann einfach eine Webadresse verwendet, unter der Informationen zu der entsprechenden Definition zu finden sind. Beispiel: http://unitsofmeasure.org ist die offizielle Informationsseite zur UCUM-Spezifikation und wird in FHIR als Canonical-URL für das entsprechende CodeSystem verwendet.

Für den Aufbau von Canonicals gibt es keine festen Regeln, folgendes Schema hat sich jedoch als unkompliziert und praktikabel erwiesen: [org]/[project]/[version]/[type]/[name]

[org] = Domäne der herausgebenden Organisation, z.B. "http://meine-domaene.de", "http://hl7.org".

Um die Canonicals auflösbar zu machen, muss in der Regel ein Redirect vom Webserver der Organisation auf die Publikationsseite der Spezifikation (z.B. Simplifier) eingerichtet werden. Dafür ist es hilfreich, wenn alle Canonicals eine gemeinsame Root haben, Das kann erreicht werden, indem stets der Pfad "/fhir/" an die Domäne angehängt oder eine Subdomäne verwendet wird z.B. "http://meine-domaene.de/fhir/" oder http://fhir.meine-domaene.de Von der Verwendung von "https" statt "http" in den Canoncials ist generell abzuraten. Hier wird sonst das Prinzip eines eindeutigen Namens für eine Ressource (was die Canoncial ist) mit der Methode zum Zugriff auf die Ressource (was die Canoncial NICHT ist) vermischt. Ein Name wird nicht "sicherer", wenn man ein "s" hinzufügt!

[project] = Projektname der Spezifikation (kann weggelassen werden, wenn es nur eine einzige organisationsweite Spezifikation gibt, ist jedoch insbesondere dann hilfreich, wenn verschiedene Teams an diesen Projekten arbeiten und sichergestellt sein soll, dass die vergebenen URls eindeutig sind, ohne dass die Teams sich über die Vergabe abstimmen müssen.)

[version] = Hauptversion der Spezifikation (sollte nur dann gesetzt werden, wenn mehrere Versionen der Spezifikation parallel betrieben werden müssen und wenn breaking changes zwischen verschiedenen Hauptversionen zu erwarten sind, sonst weglassen.

[type] = Name des Ressourcentyps des Artefakte, z.B. "StructureDefinition", "ValueSet" etc. CAVE: Bei Ressourcen vom Typ "NamingSystem" sollte hier der internationalen Praxis gefolgt werden, anstelle des Ressourcentyps das Kürzel "sid" zu verwenden, da die Bezeichnung eines NamingSystems streng genommen keine Canonical URL, sondern eine uniqueID darstellt.

Begründung: NamingSystem Ressourcen verfügen nicht über ein .url-Elemente wie es für definitorische Artefakte üblich ist. Statt dessen wird die eindeutige Bezeichnung eines Namensraumes in NamingSystem.uniqueID angegeben. Dabei handelt es sich um ein wiederholbares Element, da die Ressource auch andere/alternative/veraltete bekannte Bezeichner eines Namensraumes erfassen kann (z.B. OIDs, UUIDs etc.). Die in FHIR gebräuchliche URI wird als preferred gekennzeichnet. Diese Besonderheit der NamingSystem-Ressource hatte in der Community immer wieder für Probleme und Kritik gesorgt, so dass die NamingSystem-Ressource in FHIR R5 ein .url-Element hinzubekommen hat. Daher ist es für R4 empfehlenswert, die URL .../NamingSystem/... frei zu lassen und statt dessen das Kürzel .../sid/... für typezu verwenden.

[name] = sprechender, eindeutiger Name der Definition

Stabilität

Einmal festgelegt, sollte sich eine Canonical nicht ändern, selbst wenn die Inhalte, die sie beschreiben, aktualisiert oder modifiziert werden. Die Änderungen der Version einer Definition kann unabhängig von der Canonical geschehen. Definitionen in FHIR verfügen stets sowohl über ein url-Attribut, das gleich bleibt, als auch ein version-Attribut, das sich im Laufe der Zeit ändern kann. Dies gilt ganz besonders für Canonicals, die später massenhaft in Implementierungen verwendet werden und sich obendrein auf die Interpretation von Daten auswirken können. Dies trifft insbesondere auf die Canonicals von CodeSystemen und NamingSystems zu. ValueSet sind weniger stark betroffen, da sie nur in den Definitionen verwendet werden, nicht in den Instanzen. Auch die Umbenennung von Profilen gilt als weniger kritisch, da die Angabe eines Profilnamens in meta.profile einer Instanz keine Auswirkung auf die Interpretation einer Ressource haben sollte.

Wird eine Domäne aufgegeben, weil eine entsprechende Organisation nicht mehr existiert oder die Laufzeit eines Projektes beendet ist, muss eine Canonical nicht zwangsläufig geändert werden. Die einzige Einschränkung, die sich durch die Beibehaltung einer Canoncial, deren Domäne man nicht mehr kontrolliert, ergibt, besteht in der Schwierigkeit, die Canoncial weiterhin zur Publikation der Spezifikation auflösbar zu machen, da man den Redirect nicht länger konfigurieren kann. Da es jedoch keine Verpflichtung gibt, dass Canonicals auflösbar sein müssen, sollte dies kein Anlass sein, inkompatible Änderungen an der Spezifikation durchzuführen.

Versionsspezifische Canonicals

Bei der Referenzierung auf eine Definition mittels des Datentyps canonical kann die Version pipe-separiert mit angegeben werden, wenn sichergestellt werden soll, dass sich der Verweis immer auf dieselbe Version einer Definition bezieht, unabhängig davon, ob diese noch aktuell oder gültig ist.

Beispiel: http://hl7.org/fhir/ValueSet/data-absent-reason|4.0.1

Bei einer Canonical-Referenz ohne Versionsangabe entscheidet das jeweils interpretierende System, welche Version gilt.

Besonderheiten bei Canonicals von Extensions

Extensions werden – wie alle definitorischen Artefakte – durch eine Canonical identifiziert und referenziert.

Da der Datentyp von Extension.url jedoch “url” lautet (und nicht “canonical”), sind hier keine OIDs, UUIDs oder anderen Formen von URIs erlaubt, sondern ausschließlich URLs. Auch die versionsspezifische Notation [canonical]|[version] kann bei der Referenzierung auf Canonicals nicht verwendet werden. Bei nicht-kompatiblen Änderungen an Extensions muss daher die Canonical geändert werden.

Ändern von Canonicals

Grundsätzlich gilt: Einmal vergebene Canonicals sollten nicht mehr geändert werden, auch dann nicht, wenn z.B. eine Domäne aufgegeben wird, weil eine herausgebende Organisation nicht mehr exisitiert oder fusioniert.

Dies Auswirkung, dass eine ggf. Canonical dadurch nicht mehr auflösbar ist, stellt dabei nur ein geringfügiges Problem dar, da die Auflösbarkeit ohnehin optional ist.

Deutlich schwerwiegender wären die Auswirkungen auf Spezifikationen und Implementierungen im Falle einer Änderung (bei dieser Betrachtung wird davon ausgegangen, dass die jeweilige Definition inhaltlich identisch bleibt, und NUR die Canoncial verändert werden soll):

Die hier aufgelisteten Auswirkungen von Änderungen beziehen sich auf bis jetzt gewonnene Erfahrungen aus solchen Ereignissen und werden kontinulierlich fortgeschrieben, sofern sich neue Erkenntnisse ergeben.