Upload von Inhalten anfragen

Präambel

Die SU-TermServ ist verantwortlich für die Wartung einer Instanz von Ontoserver, die derzeit über die Universität zu Köln gehostet wird. Der Zugang wird durch einen Vertrag reguliert.

Ressourcen werden dem Server nach angemessener Benutzeranfrage hinzugefügt. Da der Server für alle Kunden innerhalb des MII und des NUM gehostet wird, muss klar sein, warum eine Ressource auf dem Server benötigt wird. Kunden können keine Ressourcen selbst hochladen, und alle hinzugefügten Ressourcen müssen den hier beschriebenen Regeln folgen.

Der auf der Website bereitgestellte Server ist eine Instanz des HL7-FHIR-basierten Terminologieservers Ontoserver von CSIRO. Daher müssen alle Ressourcen gültige FHIR-Ressourcen sein (CodeSystem, ValueSet, ConceptMap, NamingSystem, StructureDefinition).

Anfrage nach Versionen von SNOMED CT und LOINC

In Ihrer Anfrage geben Sie bitte die Version von SNOMED CT an, die Sie benötigen. Versionen von SNOMED CT sehen beispielsweise so aus: 20230831. Wenn Sie eine andere Ausgabe verwenden, müssen Sie auch die Kennung für die Ausgabe bereitstellen. Für LOINC geben Sie bitte die Versionsnummer an, die folgendermaßen aussieht: 2.73.

Stellen Sie Ihre Anfrage zum Hochladen an [email protected].

Anfrage zur Hinzufügung von FHIR-Ressourcen

Solange die von Ihnen benötigten Ressourcen Teil eines KDS-Moduls des MII sind, müssen Sie die Ressourcen nicht selbst bereitstellen, sondern nur darauf hinweisen, welche Ressourcen/Module Ihnen fehlen.

Stellen Sie Ihre Anfrage zum Hochladen an [email protected].

Namens- und Metadatenkonventionen

Abgesehen von der offensichtlichen Anforderung, dass alle Ressourcen gültige FHIR R4-Ressourcen sind, gibt es einige Metadatenanforderungen, die von uns auferlegt werden.

Für die Metadaten aller benutzerbereitgestellten Daten bitten wir darum, dass alle Metadaten den Namenskonventionen für die Erstellung von FHIR-Ressourcen in der Medizinischen Informatik-Initiative folgen, wie sie in diesem Dokument im TMF-SharePoint dargelegt sind. Die Regeln, die terminologische Ressourcen betreffen, werden hier wiedergegeben.

Format

Obwohl XML durch den FHIR-Standard unterstützt wird, werden wir nur Ressourcen im JSON-Format akzeptieren. Dies erlaubt den Einsatz und die Entwicklung von Tooling zu unserer Unterstützung anhand eines Formats anstelle der Notwendigkeit der Unterstützung von zwei äquivalenten Formaten.

Sprache

Die präferierte Sprache für Ressourcen (in description, title und name) ist Deutsch, aber wenn durch Sie präferiert, ist die Verwendung von English auch legitim.

Es KANN eine englische/deutsche Übersetzung mittels der translation extension für z.B. die Elemente description, title und title erstellt werden, um die internationale Verwendbarkeit der Ressource zu verbessern.

Im JSON-Format sieht dies z.B. so aus (im Moment gibt es aber leider offenbar kein Tooling, das Sie bei der Übersetzung unterstützt, daher müssten Sie die FHIR-Ressource manuell ändern):

{
  "title": "MII CS Demo Übersetzungsdemo",
  "_title": {
    "extension": [ {
      "url": "http://hl7.org/fhir/StructureDefinition/translation",
      "extension": [
        {
          "url": "lang",
          "valueCode": "en"
        },
        {
          "url": "content",
          "valueString": "MII CS Demo Translation demo"
        }
      ],  
      } ]
    }
}

Profile

Für CodeSystem/ValueSet-Ressourcen MÜSSEN Ihre Ressourcen diesen Profilen entsprechen:

• http://hl7.org/fhir/StructureDefinition/shareablecodesystem (Dokumentation)
• http://hl7.org/fhir/StructureDefinition/shareablevalueset (Dokumentation)

Diese Elemente sind dadurch verpflichtend: url, version, experimental, title, description, caseSensitive.

Präfixe

Hier definieren wir einige Präfixe für Ressourcen-Typen, die in dieser Spezifikation im weiteren Text verwendet werden:

Für weitere definierte Präfixe konsultieren Sie die Spezifikation im TMF-SharePoint.

Abkürzungen für Projekte und -Namensräume

Die Namenskonventionen wurden ursprünglich für Ressourcen, die Teil des MII KDS sind, verfasst. Sie erfordern, dass die Ressourcen klar einem Kümmererteam zugeordnet werden. Da Sie selber für die Pflege Ihrer Ressource verantwortlich sein werden, muss diese Zuordnung auch hier erfolgen. Dazu überlegen Sie sich einen kurzen Bezeichner für Ihr Projekt. Dieser wird an einigen Stellen in den Metadaten erforderlich sein. Hier sind eingige Beispiele aus den Namenskonventionen:

Der technische Modul-Name würde in der url, die Abkürzung in title, name und id verwendet werden.

Ein weieres Beispiel: Das Projekt SU-TermServ könnte su-termserv als technischen Modul-Namen verwenden, und SU-TermServ als Abkürzung.

Weiterhin erwarten die KDS-Richtlinien auch einen Projektnamensraum. Für KDS-Module ist dies einfach MII, für Projekte in der NUM wäre dies NUM. Für andere Verbünde, die hier nicht erwähnt werden, ist ein neuer Namespace zu definieren und verwenden.

Es gibt keine zentrale Datenbank für diese Identifier. In der Zukunft könnte aber Tooling entwickelt werden, mit dem die Ressourcen auf dem Server aufbereitet werden. Hierfür sind diese Abkürzungen relevant; daher bitten wir darum, dass die Abkürzungen intuitiv nachvollziehbar und konsistent vergeben werden. Nur so können nachvollziehbare Visualisierungen etc. generiert werden.

Dateinamen

Als Dateiname SOLL der name im Upper_Snake_Case mit der Dateiendung .json verwendet werden.

Metadaten-Elemente

title

Der title ist ein menschenlesbarer Name für die Ressource. Er erlaubt Leerzeichen und Sonderzeichen wie Umlaute (stellen Sie sicher, dass Sie UTF-8 verwenden!).

• Struktur: <Projektnamensraum> <Präfix ResourceType> <Abkürzung Projekt> <Beschreibung Inhalt> [<Weitere Informationen>]
• Beispiel für CS: MII CS Mikrobio Mikrobiologische Erreger (Bakterien, Pilze)
• Für VS ist auch die verwendete Terminologie mit einer entsprechenden Abkürzung zu kennzeichnen. Wenn kein Name offensichtlich ist, lassen Sie diese Information weg, oder verwenden Sie lokal: MII VS Mikrobio Mikrobiologische Erreger (Bakterien, Pilze) [SNOMED CT].
• Für CM, referenzieren Sie die Quell- und Ziel-Terminologie: MII CM Mikrobio Mikrobiologische Erreger (Bakterien, Pilze) [LOINC -> SNOMED CT]
• VS und CM: Wenn mehrere Quell-/Ziel-Terminologien referenziert werden, trennen Sie diese mittels Kommas.

name

Der name ist ein maschinenlesbarer Name für die Ressource. Die gleichen Regeln wie für den title gelten hier, aber der Upper_Snake_Case SOLL verwendet werden.

Beispiel: MII_VS_Mikrobio_Mikrobiologische_Erreger_Bakterien_Pilze_SNOMEDCT

id

Die id ist der logische Identifikator für die Ressource. Diese ID wird damit Bestandteil der physischen URL, unter der die Ressource nach dem Upload zur Verfügung steht.

Die FHIR-Spezifikation hat spezifische Regeln über das Format der IDs, die durch den folgenden Regulären Ausdruck ausgedrückt werden: [A-Za-z0-9\-\.]{1,64}. Dies bedeutet:

• alle Zeichen müssen US-ASCII sein.
• Die einzigen erlaubten Sonderzeichen sind Bindestriche - und Punkte .
• Die Länge des Strings ist auf 64 begrenzt.

Daher SOLL die id mittels des gleichen Verfahrens wie name generiert werden, aber alle Unterstriche _ durch Bindestriche - ersetzt werden. Sofern die so generierte ID länger als 64 Zeichen ist, MUSS die ID entsprechend gekürzt werden, die Grenze von 64 Zeichen ist eine harte Grenze aus dem FHIR-Standard. Wir bitten zu bedenken, dass häufig eine lange ID, die knapp an der Grenze liegt, besser verständlich sein wird, als eine, bei der viel gekürzt wurde.

Beispiel: mii-vs-mikrobio-mikrobiologische-erreger-snomedct (49 Zeichen)

Benötigen Sie mehrere Versionen der gleichen Ressource im Zugriff über die FHIR-Terminologieoperationen, so erfordert dies eine Anpassung der IDs. Anderenfalls wird die Ressource bei einem Update bzw. beim Upload einer neuen Version des Packages (siehe unten) überschrieben und ist nur noch über den vread-Mechanismus von FHIR zugreifbar.

In diesem Falle SOLLEN die letzten Zeichen der ID den Versionstring wiedergeben, getrennt mit einem Bindestrich -. Es kann sein, dass hierfür Kürzungen an anderer Stelle der ID notwendig sind.

Beispiel: mii-vs-mikrobio-mikrobiologische-erreger-snomedct-1.0.1-alpha1 (62 Zeichen, hier via SemVer)

url

Die kanonische URL(canonical URL) ist der eine und einzige authoritative Identifikator für die Ressource.

Die Aussagen in den Namenskonventionen der MII zum Aufbau der kanonischen URLs sind so nur für die KDS-Module anwendbar. Darüber hinaus sind Änderungen der kanonischen URL nach der erstmaligen Veröffentlichung mit einigem Aufwand bei der Änderung von davon abhängigen Ressourcen verbunden ist. Daher werden hier nur Empfehlungen getroffen, von denen abgewichen werden DARF. URLs MÜSSEN aber stets global eindeutig gewählt werden.

Die Medizininformatik-Iniatiative schreibt dazu folgende Struktur vor (zumindest für neue Ressourcen):

https://www.medizininformatik-initiative.de/fhir/<technischer Modulname>/<Ressourcentyp>/<id der Ressource>

Falls noch keine Abhängigkeiten zu Ihren Ressourcen bestehen, ist dieser Aufbau ein geeigneter Ansatzpunkt. Für eine ConceptMap vom Projekt SU-TermServ wäre dies zum Beispiel eine geeignete URL:

https://mii-termserv.de/fhir/su-termserv/ConceptMap/sutermserv-cm-demo-map-snomedct-icd10gm

OIDs hingegen SOLLEN NICHT als kanonische URLs für FHIR-Ressourcen verwendet werden, weil sie nicht menschenlesbar sind. OIDs KÖNNEN im identifier-Element mit dem identifier.system auf urn:ietf:rfc:3986 repräsentiert werden, wobei die OID im Feld identifier.value mit dem Präfix urn:oid: zu versehen ist.

Beispiel für die Verwendung einer OID im Identifier:

{
  "identifier": [{
    "system": "urn:ietf:rfc:3986",
    "value": "urn:oid:0.4.0.127.0.16.1.1.2.1"
  }]
}

version

Um die Version durch den Ontoserver interpretierbar zu machen, sind zwei Formate erlaubt, und Sie DÜRFEN eines dieser beiden auswählen. Dadurch kann Ontoserver automatisch die aktuelle Version einer Ressource bestimmen, und verwendet diese automatisch, solange keine Version in der Anfrage explizit angefragt wird.

1. Verwenden Sie das Datum der Publikation im Format YYYYMMdd (z.B. 20230131)
2. Verwenden Sie Semantic Versioning (z.B. 1.0.0 < 1.0.1-alpha < 1.0.1-rc < 1.0.0)

Sie KÖNNEN auch mittels des in FHIR R5 neuen Elements versionAlgorithm codieren, welche Versionierung Sie verwenden. Die Codes entstammen dann aus (https://hl7.org/fhir/ValueSet/version-algorithm)[http://hl7.org/fhir/ValueSet/version-algorithm]. Dies ist aber nicht erforderlich.

description

Die description MUSS durch das CS/VS-Profil obligat ausgefüllt werden; hier können Sie auch detaillierte Angaben zur Herkunft der Ressource, zum Use Case, etc. angeben.

copyright, publisher, contact

In diesen Elementen KÖNNEN Sie weitere Informationen zu Ihrer Ressource angeben.

Für copyright ist die Verwendung der SPDX License Identifiers ratsam.

In publisher nennen Sie den langen Namen Ihres Projekts; während konkrete Kontaktdetails, eventuell auch einzelner Personen, in contact getroffen werden können.

meta.tag

Mittels der tags können workflow-spezifische Informationen an FHIR-Ressourcen angefügt werden.

Hierzu haben wir Ressourcen erstellt, die per NPM-Package bereitgestellt werden:

• CodeSystem mit Canonical https://mii-termserv.de/fhir/su-termserv/CodeSystem/mii-cs-suts-resource-tags-project (physisch, Expansion): hiermit kann der grobe Projekt-Namensraum definiert werden.
• CodeSystem mit Canonical https://mii-termserv.de/fhir/su-termserv/CodeSystem/mii-cs-suts-resource-tags-dataset (physisch, Expansion): hiermit kann eine Ressource einem Datensatz zugeordnet werden.

Sie KÖNNEN diese Tags selbstständig an Ihre Ressourcen hinzufügen. Wir behalten uns vor, diese Tags selbstständig zu ergänzen, da hierüber relativ leicht Tooling implementiert werden kann, das Ressourcen semantisch gruppiert.

Falls in den Ressourcen ein Wert für Sie fehlt, melden Sie sich gerne, damit die CodeSystems entsprechend aktualisiert werden können.

Sie DÜRFEN selbstverständlich mehr als ein Tag mit der gleichen URL hinzufügen, und DÜRFEN jedes beliebige weitere Tag verwenden.

Paketierung der Ressourcen

Ressourcen, die durch uns hochgeladen werden (mit der Ausnahme von SNOMED CT und LOINC, siehe oben) SOLLEN als FHIR Package gebündelt werden. Dieses Paket SOLL öffentlich gemacht werden. Der Upload von “geheimen” Ressourcen ist durch uns nicht erwünscht.

Anforderungen an Pakete

Es ist nicht notwendig, ein eigenes Paket nur mit den terminologischen Ressourcen neben Ihrem eigentlichen ImplementationGuide zu erstellen, wünschen Sie dieses, ist dies aber natürlich auch in Ordnung. Sie sind dann aber dafür verantwortlich, die Synchronizität zwischen dem Terminologie-Paket und der eigentlichen Veröffentlichung zu gewährleisten.

Sollten Sie ein spezifisches Paket für die Veröffentlichung auf dem zentralen Ontoserver erstellen, so ist kein ImplementationGuide für die Ressourcen erforderlich, wenn nicht vielleicht ratsam.

Packages werden durch uns nur komplett hochgeladen, d.h. wir werden nicht einzelne terminologische Ressourcen aus dem Package auf Anfrage entfernen.

Ressourcen SOLLEN bis auf weiteres gemäß FHIR R4 bzw. FHIR R4B erstellt werden, solange noch keine adäquate Tool-Unterstützung für R5-ConceptMaps besteht. Für CS und VS stimmt die Spezifikation von R4 und R5 überein, sodass hier keine Änderungen erforderlich sind.

In Ihrer Anfrage an die SU-TermServ nennen Sie bitte den Link zum öffentlichen Package in der gewünschten Version.

Distributions-Optionen für Pakete

Simplifier.net

Sie KÖNNEN ein Projekt und assoziertes Projekt auf der Simplifier.net-Plattform erstellen. Dies kann eine kostenpflichtige Lizenz erfordern. Für die Erstellung des Paketes sei auf die Dokumentation von Simplifier verwiesen.

Mittels der offiziellen FHIR-Registry

HL7 International stellt ebenfalls eine Registry bereit. Die Hürde zum Upload Ihres Paketes scheint aber vergleichsweise hoch, sofern Sie nicht Simplifier verwenden. Es sei auf die Dokumentation der Registry verwiesen.

GitLab Package Registry

GitLab stellt eine Möglichkeit zur Distribution von öffentlichen (und privaten) NPM-Paketen mittels projekt-spezifischer Registries bereit. Wir haben ein Template-Repository erstellt, in dem die Erstellung eines Paketes illustriert wird. Mehr Informationen finden Sie im README in diesem Repository, sowie in der GitLab-Dokumentation.

Diese Option ist für Sie mit keinen Kosten verbunden, da das Repository öffentlich sein muss.

Mittels der GitHub Package Registry

So wie GitLab stellt auch GitHub die Möglichkeit bereit, NPM-Pakete zu verteilen. Es sei auf die Dokumentation von GitHub sowie auf das oben erwähnte GitLab-Template verwiesen.

Diese Option ist für Sie mit keinen Kosten verbunden, da das Repository öffentlich sein muss.

Versionierung und Updates

Wenn Sie Ihr Package updaten, senden Sie bitte erneut eine Anfrage per E-Mail. Ohne einen Auftrag werden wir nicht selbstständig tätig.

Sofern Sie keine anderen Aussagen treffen, wird nur die aktuelle Version des Paketes bereitgestellt und keine Ressourcen werden gelöscht. Sofern also in einem Paket eine Ressource gelöscht wird, wird eine ältere Version auf dem Server erhalten bleiben. Wünschen Sie hier die Löschung, ist dies entsprechend zu erwähnen.

Beachten Sie, dass für den Fall, dass mehrere Versionen der gleichen Ressource benötigt werden, auf die id zu achten ist, dafür siehe oben.

Da der Server FHIR-basiert ist, werden ältere Ressourcen-Versionen weiterhin über den vread-Mechanismus erreichbar bleiben. Dies ist eine Anforderung des FHIR-Standards und kann nicht deaktiviert oder umgangen werden. Dies trifft auch auf Löschungen von Ressourcen zu. Solange der Server nicht mit einer frischen Datenbank neu deployed wird, was wir ohne Vorankündigung im Rahmen der regulären Wartungsarbeiten und Downtimes jederzeit durchführen können, bleiben gelöschte Ressourcen erreichbar.

Ausnahmen

Sollten Sie zentralen Zugriff auf Ressourcen benötigen, deren Erstellung/Pflege nicht in Ihrer Zuständigkeit liegt, können Sie ebenfalls eine Anfrage auf den Upload dieses Packages stellen. Begründen Sie in Ihrer E-Mail entsprechend kurz, warum diese Ressourcen durch Ihr Projekt benötigt werden.

Hier kann entsprechend von den Namenskonventionen abgewichen werden, wir behalten uns aber vor, ggf. name, id, title vor dem Upload abzuändern. Versionen und url werden durch uns aber selbstverständlich nicht geändert.

Diese Ausnahme erfordert aber weiterhin, dass die Ressourcen als FHIR-Package zur Verfügung stehen.

Unterstützung

Sollten Sie bei der Erstellung von Ressourcen oder Packages Unterstützung benötigen, können Sie sich per E-Mail oder Zulip an das SU-TermServ-Team wenden.

Versionshistorie

• 1.1.0 (2024-05-08): Verwendung des name als Dateiname
• 1.0.0 (2023-11-06): Initiale Version