Implementation Guide
Telematikinfrastruktur (TI) Common
Version 1.1.1 - release

## Generelle Prinzipien

Dieser Implementation Guide verwendet die Schlüsselwörter MUSS, DARF NICHT, SOLL NICHT und KANN als deutsche Pendants des [RFC2119], um Anforderungen als Ausdruck normativer Festlegungen zu kennzeichnen.

### Eindeutigkeit von FHIR-Ressourcen

Der FHIR Data Service MUSS ausschließlich zeitbasierte Universally Unique IDentifier (UUID) gemäß [RFC9562] für logische IDs (d.h. FHIR-Element Resource.id) verwenden.

### Must Support in FHIR-Profilen

Die Deklarierung als Must Support wird in der Anzeige der FHIR-Profile durch ein rotes “S” gekennzeichnet. Als Must Support deklarierte Elemente MÜSSEN durch jedes Client-System, welches diese Spezifikation implementiert, unterstützt werden. Das bedeutet:

Ein Client-System, das schreibend ein FHIR-Profil des FHIR Data Service implementiert, MUSS jedes als Must Support gekennzeichnete Element gemäß der dazugehörigen Kardinalitätsangabe befüllen. Das heißt auch, dass in optionalen Elementen (z. B. Kardinalität "0..1", "0..*") der Elementwert leer bleiben darf, sofern dem Client-System kein Wert zur Verfügung steht. Das Client-System, das lesend ein FHIR-Profil des FHIR Data Service implementiert, MUSS in der Lage sein, alle Must-Support-Elemente in FHIR-Instanzen zu verarbeiten. Das Client-System MUSS auch Must-Support-Elemente ohne Wert verarbeiten können, ohne mit einem Fehler abzubrechen oder die Anwendung abstürzen zu lassen. Wenn eine Anforderung vom Client-System verlangt, Inhalte einer oder mehrerer Instanzen von FHIR-Profilen des FHIR Data Service anzuzeigen, die das Client-System implementiert, MUSS das entsprechende Client-System alle Must-Support-Elemente für die menschliche Nutzung anzeigen. Es muss dabei nicht jeden Wert genauso darstellen, wie er in der Instanz kodiert ist, darf aber auch keine wesentlichen Informationen ausblenden.

### Versionierung

Jede Änderung an einer FHIR-Instanz führt zu einer neuen Version dieser Instanz, wobei jede Version eine eindeutige Meta.versionId und ein Meta.lastUpdated erhält. Auch eine neu erstellte FHIR-Instanz wird vom FHIR Data Service mit diesen Metadaten versehen. Dadurch kann der vollständige Änderungsverlauf einer Instanz nachvollzogen werden. Der FHIR Data Service speichert und stellt die Historie aller Versionen einer FHIR-Instanz bereit. Dies umfasst auch die Möglichkeit, frühere Versionen einer Instanz über die FHIR API unter Verwendung der Meta.versionId abzurufen. Falls eine FHIR-Instanz gleichzeitig aktualisiert wird, erkennt der FHIR Data Service potenzielle Konflikte und verarbeitet diese entsprechend.

Bei einer Aktualisierung einer FHIR-Instanz, die keine inhaltlichen Änderungen an den bestehenden Werten vornimmt, bleibt die aktuelle Version der Instanz unverändert. Der FHIR Data Service erstellt in diesem Fall keine neue Version und behält den bestehenden Wert in Meta.versionId sowie das Datum in Meta.lastUpdated bei.

Der FHIR Data Service MUSS jede neu erstellte oder neu hinzugefügte FHIR-Instanz mit einer Meta.versionId und einem Meta.lastUpdated versehen, um die Versionierung sicherzustellen. Der FHIR Data Service MUSS sicherstellen, dass bei jeder Aktualisierung einer FHIR-Instanz die Meta.versionId angepasst wird. Meta.lastUpdated MUSS auf den Zeitpunkt der Aktualisierung gesetzt werden. Der FHIR Data Service MUSS sicherstellen, dass bei einer Aktualisierung einer FHIR-Instanz, die keine inhaltlichen Änderungen an den bestehenden Werten vornimmt, die aktuelle Version unverändert bleibt. In diesem Fall wird keine neue Version erstellt und die bestehende Meta.versionId sowie das Meta.lastUpdated-Datum bleiben erhalten.

#### Format für Resource.meta.versionId

Das Metadatenattribut `Resource.meta.versionId` gibt die Versionsnummer einer FHIR-Instanz an. Die FHIR R4 Spezifikation definiert kein spezifisches Format für dieses Element. Die Vergabe und Verwaltung der versionId liegt ausschließlich beim FHIR Data Service.

Der FHIR Data Service MUSS sicherstellen, dass das Element Resource.meta.versionId ausschließlich numerische Werte enthält. Alphanumerische Zeichen, Symbole oder Sonderzeichen dürfen nicht verwendet werden. Der FHIR Data Service MUSS sicherstellen, dass die versionId einer FHIR-Instanz bei jeder neuen Version um genau 1 erhöht wird. Die erste Version einer FHIR-Instanz erhält die versionId 1, die nächste Version 2, und so weiter. Beispiel: 1 → 2 → 3 → Der FHIR Data Service MUSS sicherstellen, dass die Resource.meta.versionId innerhalb einer spezifischen FHIR-Instanz eindeutig ist. Die Versionsnummer darf nicht zurückgesetzt oder übersprungen werden. Jede Instanz besitzt eine eigene fortlaufende Versionsnummer, die bei jeder Änderung der FHIR-Instanz aufsteigt.

#### Abfrage der Versionhistorie über HTTP GET

Die _history-Abfrage beim FHIR Data Service ermöglicht es, die Versionshistorie entweder einer spezifischen FHIR-Instanz oder aller Instanzen eines bestimmten ResourceType abzurufen. Damit kann nachverfolgt werden, welche Änderungen an einer Instanz vorgenommen wurden und welche Versionen im Laufe ihres Lebenszyklus existieren.

Abruf der Versionshistorie einer spezifischen Instanz

Die URL für den Abruf der Versionhistorie einer FHIR-Instanz folgt diesem Muster:

    GET [base]/[ResourceType]/[id]/_history

Dabei ist:

- ResourceType der Typ der Ressource (z.B. MedicationRequest, MedicationDispense),
- id die eindeutige ID der Ressource,
- _history die Anzeige der Versionshistorie der Instanz, welche abgerufen werden soll

Abruf der Versionshistorie aller Instanzen eines Ressourcentyps

Die URL für den Abruf der Versionshistorie aller Instanzen eines Ressourcentyps folgt diesem Muster:

    GET [base]/[ResourceType]/_history

Dabei gilt:

- ResourceType ist der Typ der Ressource (z.B. MedicationRequest, MedicationDispense)
- _history – zeigt an, dass die Versionshistorien aller Instanzen dieses Ressourcentyps abgerufen werden sollen

Funktionalität und Verhalten:

- Der FHIR Data Service gibt als Antwort ein Bundle mit dem Typ history zurück.
- Das Bundle enthält eine Liste aller bekannten Versionen der angeforderten FHIR-Instanz.
- Jede Version wird als entry innerhalb des Bundles dargestellt und enthält die entsprechenden Metadaten (meta.versionId, meta.lastUpdated)
- Falls die FHIR-Instanz gelöscht wurde, bleibt ihre Historie weiterhin abrufbar.

Beispiel für ein Bundle mit dem Typ history

    {
      "resourceType" : "Bundle",
      "id" : "example-history-bundle",
      "type" : "history",
      "total" : 2,
      "link" : [
        {
          "relation" : "self",
          "url" : "/epa/medication/api/v1/fhir/MedicationDispense/4e6e1623-778e-44a3-b208-8479f5339e43/_history"
        }
      ],
      "entry" : [
        {
          "fullUrl" : "http://epa4all/epa/medication/api/v1/fhir/MedicationDispense/4e6e1623-778e-44a3-b208-8479f5339e43",
          "request" : {
            "method" : "DELETE",
            "url" : "MedicationDispense/4e6e1623-778e-44a3-b208-8479f5339e43/_history/2"
          },
          "response" : {
            "status" : "200 OK",
            "lastModified" : "2025-08-22T15:00:00.000Z"
          }
        },
        {
          "fullUrl" : "http://epa4all/epa/medication/api/v1/fhir/MedicationDispense/4e6e1623-778e-44a3-b208-8479f5339e43",
          "resource" : {
            "resourceType" : "MedicationDispense",
            "id" : "4e6e1623-778e-44a3-b208-8479f5339e43",
            "meta" : {
              "versionId" : "1",
              "lastUpdated" : "2025-08-22T14:43:33.244Z",
              "profile" : [
                "https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication-dispense"
              ]
            },
            "extension" : [
              {
                "url" : "https://gematik.de/fhir/epa-medication/StructureDefinition/rx-prescription-process-identifier-extension",
                "valueIdentifier" : {
                  "system" : "https://gematik.de/fhir/epa-medication/sid/rx-prescription-process-identifier",
                  "value" : "162.153.303.257.459_20250301"
                }
              }
            ],
            "status" : "completed",
            "medicationReference" : {
              "reference" : "Medication/16e5611a-911c-4c0e-a705-43b0e4e79cf6"
            },
            "subject" : {
              "identifier" : {
                "system" : "http://fhir.de/sid/gkv/kvid-10",
                "value" : "X110411319"
              }
            },
            "performer" : [
              {
                "actor" : {
                  "reference" : "Organization/a2ce62fc-1f29-4759-863e-1a1ca7f9669e"
                }
              }
            ],
            "authorizingPrescription" : [
              {
                "reference" : "MedicationRequest/f434862b-9bf8-414d-8b94-5eaa0b4bbf01"
              }
            ],
            "whenHandedOver" : "2025-08-22",
            "dosageInstruction" : [
              {
                "text" : "1-0-0-0"
              }
            ],
            "substitution" : {
              "wasSubstituted" : false
            }
          },
          "request" : {
            "method" : "POST",
            "url" : "MedicationDispense/4e6e1623-778e-44a3-b208-8479f5339e43/_history/1"
          },
          "response" : {
            "status" : "201 Created",
            "lastModified" : "2025-08-22T14:43:33.244Z"
          }
        }
      ]
    }

    <Bundle xmlns="http://hl7.org/fhir">
      <id value="example-history-bundle"/>
      <type value="history"/>
      <total value="2"/>
      <link>
        <relation value="self"/>
        <url
             value="/epa/medication/api/v1/fhir/MedicationDispense/4e6e1623-778e-44a3-b208-8479f5339e43/_history"/>
      </link>
      <entry>
        <fullUrl
                 value="http://epa4all/epa/medication/api/v1/fhir/MedicationDispense/4e6e1623-778e-44a3-b208-8479f5339e43"/>
        <request>
          <method value="DELETE"/>
          <url
               value="MedicationDispense/4e6e1623-778e-44a3-b208-8479f5339e43/_history/2"/>
        </request>
        <response>
          <status value="200 OK"/>
          <lastModified value="2025-08-22T15:00:00.000Z"/>
        </response>
      </entry>
      <entry>
        <fullUrl
                 value="http://epa4all/epa/medication/api/v1/fhir/MedicationDispense/4e6e1623-778e-44a3-b208-8479f5339e43"/>
        <resource>
          <MedicationDispense>
            <id value="4e6e1623-778e-44a3-b208-8479f5339e43"/>
            <meta>
              <versionId value="1"/>
              <lastUpdated value="2025-08-22T14:43:33.244Z"/>
              <profile
                       value="https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication-dispense"/>
            </meta>
            <extension
                       url="https://gematik.de/fhir/epa-medication/StructureDefinition/rx-prescription-process-identifier-extension">
              <valueIdentifier>
                <system
                        value="https://gematik.de/fhir/epa-medication/sid/rx-prescription-process-identifier"/>
                <value value="162.153.303.257.459_20250301"/>
              </valueIdentifier>
            </extension>
            <status value="completed"/>
            <medicationReference>
              <reference value="Medication/16e5611a-911c-4c0e-a705-43b0e4e79cf6"/>
            </medicationReference>
            <subject>
              <identifier>
                <system value="http://fhir.de/sid/gkv/kvid-10"/>
                <value value="X110411319"/>
              </identifier>
            </subject>
            <performer>
              <actor>
                <reference
                           value="Organization/a2ce62fc-1f29-4759-863e-1a1ca7f9669e"/>
              </actor>
            </performer>
            <authorizingPrescription>
              <reference
                         value="MedicationRequest/f434862b-9bf8-414d-8b94-5eaa0b4bbf01"/>
            </authorizingPrescription>
            <whenHandedOver value="2025-08-22"/>
            <dosageInstruction>
              <text value="1-0-0-0"/>
            </dosageInstruction>
            <substitution>
              <wasSubstituted value="false"/>
            </substitution>
          </MedicationDispense>
        </resource>
        <request>
          <method value="POST"/>
          <url
               value="MedicationDispense/4e6e1623-778e-44a3-b208-8479f5339e43/_history/1"/>
        </request>
        <response>
          <status value="201 Created"/>
          <lastModified value="2025-08-22T14:43:33.244Z"/>
        </response>
      </entry>
    </Bundle>

Der FHIR Data Service MUSS die _history-Abfrage gemäß der HL7 FHIR Spezifikation [FHIR History Interaction] implementieren, um die Versionshistorie einer FHIR-Instanz abrufbar zu machen. Der FHIR Data Service MUSS ermöglichen, die Versionshistorie aller Instanzen eines bestimmten Ressourcentyps über eine HTTP GET-Anfrage an folgende URL abzurufen: [base]/[ResourceType]/_history. Der FHIR Data Service MUSS ermöglichen, die Versionshistorie einer FHIR-Instanz über eine HTTP GET-Anfrage an folgende URL abzurufen: [base]/[ResourceType]/[id]/_history. Der FHIR Data Service MUSS als Antwort auf eine _history-Abfrage ein Bundle mit dem Typ history zurückgeben, das die Versionen der angeforderten FHIR-Instanz enthält. Der FHIR Data Service MUSS innerhalb des _history Bundle für jede Version einer FHIR-Instanz die zugehörigen entry.request- und entry.response-Elemente bereitstellen.

- Das entry.request-Element MUSS die Methode (method) und die URL (url) enthalten, unter der diese spezifische Version abrufbar ist.
- Das entry.response-Element MUSS den Status (status) sowie das Datum der letzten Änderung (lastModified) enthalten.

#### Abfrage einer spezifischen Version über HTTP GET

Um eine spezifische Version einer Ressource abzurufen, kann eine einfache HTTP GET-Anfrage an den FHIR Data Service gesendet werden. Die URL für den Abruf einer bestimmten Version einer FHIR-Instanz folgt diesem Muster:

    GET [base]/[ResourceType]/[id]/_history/[versionId]

Dabei ist:

- resourceType der Typ der Ressource (z.B. Medication, MedicationStatement)
- id die eindeutige ID der Ressource
- versionId die spezifische Meta.versionId der abzurufenden Ressourcenversion

Beispiel

Um die 3. Version einer `MedicationStatement`-Instanz mit der ID “391fc0c6-e045-48d9-8af6-3ac2466beb88” vom FHIR Data Service abzurufen, muss die URL für die HTTP GET-Anfrage wie folgt aussehen:

    GET [base]/epa/medication/api/v1/fhir/MedicationStatement/391fc0c6-e045-48d9-8af6-3ac2466beb88/_history/3

Der FHIR Data Service MUSS das Lesen spezifischer Versionen von FHIR-Instanzen gemäß der HL7 FHIR Spezifikation [FHIR Version Read] implementieren. Dabei MUSS eine angeforderte Version einer Instanz über eine GET-Anfrage der Form [base]/[resourceType]/[id]/_history/[versionId] bereitgestellt werden. Die Antwort MUSS die angeforderte Version der Instanz enthalten, einschließlich der zugehörigen Metadaten (meta.versionId, meta.lastUpdated). Der FHIR Data Service MUSS sicherstellen, dass eine spezifische Version einer Ressource über die Meta.versionId eindeutig identifiziert und abgerufen werden kann. Die versionId dient dabei zur referenzgenauen Anforderung einer bestimmten historischen Version einer Ressource. Der FHIR Data Service MUSS bei einem GET-Request auf eine spezifische Version einer FHIR-Instanz den HTTP Status Code 404 (Not Found) zurückgeben, wenn die angeforderte Version nicht existiert.
Die Response MUSS eine OperationOutcome-Ressource enthalten mit folgenden Eigenschaften:

- OperationOutcome.issue.code auf not-found gesetzt.
- OperationOutcome.issue.diagnostics mit einer Meldung, dass die angeforderte Version nicht existiert.

#### Löschen als Versionierungsergebnis

Im FHIR Data Service wird das Löschen einer Ressource als ein weiteres Ereignis im Lebenszyklus einer Ressource behandelt. Das bedeutet: Anstatt die Ressource physisch zu entfernen, wird die Ressource als gelöscht markiert und eine neue Version der Ressource erstellt, welche diesen Zustand widerspiegelt. Obwohl eine Ressource als gelöscht markiert wurde, können frühere Versionen über die versionsspezifischen Endpunkte (s.o.) abgerufen werden.

Der FHIR Data Service MUSS das Löschen einer Instanz als ein Ereignis im Lebenszyklus der Instanz behandeln, indem eine neue Version erstellt wird, die den gelöschten Zustand widerspiegelt. Der FHIR Data Service MUSS eine als gelöscht markierte Instanz weiterhin in der Versionshistorie speichern, anstatt sie physisch zu entfernen. Der FHIR Data Service MUSS sicherstellen, dass frühere Versionen einer gelöschten Instanz weiterhin über versionsspezifische Endpunkte abrufbar sind. Der FHIR Data Service MUSS bei einem GET-Request auf eine gelöschte FHIR-Instanz oder eine gelöschte Version den HTTP Status Code 410 (Gone) zurückgeben.
Dies gilt für:

- [ResourceType]/[id] – wenn die gesamte FHIR-Instanz gelöscht wurde
- [ResourceType]/[id]/_history/[versionId] – wenn eine spezifische Version der FHIR-Instanz gelöscht wurde

Die Response MUSS eine OperationOutcome-Ressource enthalten mit folgenden Eigenschaften:

- OperationOutcome.issue.code ist auf processing gesetzt
- OperationOutcome.issue.details ist auf MSG_DELETED gesetzt
- OperationOutcome.issue.diagnostics enthält eine Meldung, dass die Instanz gelöscht wurde

Das folgende Beispiel zeigt die erwartete Antwort nach dem Abruf einer gelöschten Instanz.

    {
      "resourceType" : "OperationOutcome",
      "id" : "0dc58d79-1b2e-4c6f-afe0-0a5b721661a2",
      "meta" : {
        "profile" : [
          🔗 "https://gematik.de/fhir/ti/StructureDefinition/operation-outcome"
        ]
      },
      "issue" : [
        {
          "severity" : "error",
          "code" : "processing",
          "details" : {
            "coding" : [
              {
                "system" : "http://terminology.hl7.org/CodeSystem/operation-outcome",
                "code" : "MSG_DELETED",
                "display" : "This resource has been deleted"
              }
            ]
          },
          "diagnostics" : "Resource was deleted at 2025-03-10T10:02:27.838+00:00"
        }
      ]
    }

    <OperationOutcome xmlns="http://hl7.org/fhir">
      <id value="0dc58d79-1b2e-4c6f-afe0-0a5b721661a2"/>
      <meta>
        <profile
                 value="https://gematik.de/fhir/ti/StructureDefinition/operation-outcome"/>
      </meta>
      <issue>
        <severity value="error"/>
        <code value="processing"/>
        <details>
          <coding>
            <system
                    value="http://terminology.hl7.org/CodeSystem/operation-outcome"/>
            <code value="MSG_DELETED"/>
            <display value="This resource has been deleted"/>
          </coding>
        </details>
        <diagnostics
                     value="Resource was deleted at 2025-03-10T10:02:27.838+00:00"/>
      </issue>
    </OperationOutcome>

Der FHIR Data Service MUSS innerhalb des _history Bundle auch gelöschte Versionen einer FHIR-Instanz dokumentieren.

- Das entry.request-Element MUSS die Methode (method = DELETE) und die URL (url) enthalten.
- Das entry.response-Element MUSS den Status (status = 200 OK) sowie das Löschdatum (lastModified) enthalten.
- Das entry.resource-Element DARF für die gelöschte Version NICHT enthalten sein

#### Versionierte Referenzen

Versionierte Referenzen in FHIR ermöglichen es, innerhalb einer FHIR-Ressource auf eine spezifische Version einer anderen Ressource zu verweisen. Dies ist besonders wichtig in Szenarien, in denen die Genauigkeit und der Kontext der bezogenen Daten über die Zeit erhalten bleiben müssen.

In FHIR kann eine Referenz auf eine andere Ressource in der Regel durch die Angabe des Ressourcentyps und der ID erfolgen. Versionierte Referenzen erweitern dieses Konzept, indem sie es ermöglichen, zusätzlich die Version der referenzierten Ressource anzugeben. Dies stellt sicher, dass immer auf den exakten Zustand der referenzierten Ressource zum Zeitpunkt der Referenzerstellung Bezug genommen wird, unabhängig von späteren Änderungen oder Aktualisierungen dieser Ressource.

Eine versionierte Referenz in FHIR beinhaltet den Ressourcentyp, die Ressourcen-ID und die spezifische Meta.versionId der referenzierten Ressource. Das Format sieht wie folgt aus:

    [ResourceType]/[id]/_history/[versionId]

Beispiel für eine versionierte Referenz auf eine spezifische Version einer MedicationStatement-Instanz:

    MedicationStatement/391fc0c6-e045-48d9-8af6-3ac2466beb88/_history/4

In diesem Beispiel bezieht sich die Referenz auf die 4. Version der MedicationStatement-Instanz mit der ID 391fc0c6-e045-48d9-8af6-3ac2466beb88.

Der FHIR Data Service MUSS die Versionierte Referenzen nach [FHIR References and Versions] implementieren. Der FHIR Data Service MUSS versionierte Referenzen unterstützen, um es zu ermöglichen, innerhalb einer FHIR-Instanz auf eine spezifische Version einer anderen Instanz zu verweisen. Der FHIR Data Service MUSS sicherstellen, dass eine FHIR-Instanz eine andere Instanz nicht nur über Ressourcentyp und ID, sondern auch mit einer spezifischen Meta.versionId referenzieren kann. Der FHIR Data Service MUSS das Format für versionierte Referenzen verwenden, das den Ressourcentyp, die Resource.id und die Meta.versionId beinhaltet: [ResourceType]/[id]/_history/[versionId]. Der FHIR Data Service MUSS sicherstellen, dass versionierte Referenzen in Bundles entsprechend den Vorgaben in [FHIR Bundle References] auflösbar sind.

Zum Auflösen einer versionerten Referenz, muss zunächst ein Treffer auf Grund der Referenz ohne die Versionsinformation (also ohne `/_history/[versionId]`) mit der `Bundle.entry.fullUrl` bestimmt werden muss und anschließend die Version mit `Resource.meta.versionId` auf Übereinstimmung geprüft werden (siehe [FHIR Bundle References]). Hierbei muss die `Bundle.entry.fullUrl` nicht eindeutig sein (siehe [FHIR Bundle.entry.fullUrl]) und mehrere Versionen der selben Resourcen-Instanz mit der selben URL innerhalb eines Bundles erlaubt.

### Persistieren der Profilversion in FHIR

Beim Erzeugen von FHIR-Ressourcen im FHIR Data Service MUSS dieser jede zu speichernde Ressource gegen das dazugehörige aktuelle Profil validieren. Die Information, gegen welches Profil in welcher Version geprüft wurde, MUSS der FHIR Data Service in der jeweiligen Ressource in Meta.profile speichern.

### Bereitstellung von Capability Statements

Ein FHIR Data Service MUSS an dem Endpunkt /metadata gemäß der [Capabilities-Interaktion] ein Capability Statement Typ kind = instance bereitstellen. Dieses Capability Statement muss im Element software den Namen und die Versionsnummer der eingesetzten Software angeben. Dieses Capability Statement muss sämtliche Anforderungen an den FHIR Data Service aus dem Capability Statement vom Typ kind = requirements der zugrundeliegenden Spezifikation erfüllen.

### Verwendung von Codes im Status inactive

Der FHIR Data Service MUSS das Registrieren und Speichern von neuen Daten ablehnen und mit dem Fehler SVC_INACTIVE_CODE quittieren, falls ein Code den Status inactive besitzt. Unter OperationOutcome.issue.diagnostics MUSS der FHIR Data Service angeben, welcher Code nicht mehr unterstützt wird.