Merge pull request #214 from gematik/feature/reference-description

Beschreibungen für Referenzierung
gematik · Nov 25, 2024 · bb7669e · bb7669e
2 parents 2e27f9e + f63d560
commit bb7669e
Show file tree

Hide file tree

Showing 2 changed files with 210 additions and 0 deletions.
diff --git a/docs/erp_fhir_infos.adoc b/docs/erp_fhir_infos.adoc
@@ -57,6 +57,7 @@ Durchgängige Beispieldatensätze von der Verordnung und qualifizierter Signatur
 === Referenzierung von FHIR-Objekten in Bundles
 Der FHIR-Standard definiert wie Ressourcen in einem Bundle referenziert werden sollen. Siehe hierzu link:https://hl7.org/fhir/R4/references.html[Referezen] und link:http://hl7.org/fhir/R4/bundle.html[Bundles].
 
+==== Übereinstimmung von id und fullUrl
 Bei Verwendung von relativer Referenzierung in Bundles muss darauf geachtet werden, dass die id der fullUrl der Ressource mit der id der Ressource übereinstimmt.
 
 Beispielsweise ist folgende Konstellation ungültig, da der hintere Teil der fullUrl nicht mit der Ressourcen-ID übereinstimmt (b54dd6cad655 ≠ 000000000000):
@@ -69,6 +70,110 @@ Beispielsweise ist folgende Konstellation ungültig, da der hintere Teil der ful
                 <id value="bc329f24-3d65-4286-bf06-000000000000" />
 ----
 
+Hier das korrigierte Beispiel:
+[source,xml]
+----
+<fullUrl value="http://pvs.praxis.local/fhir/Practitioner/bc329f24-3d65-4286-bf06-b54dd6cad655" />
+        <resource>
+            <Practitioner xmlns="http://hl7.org/fhir">
+                <id value="bc329f24-3d65-4286-bf06-b54dd6cad655" />
+----
+
+==== Einheitliche Referenzierung in Bundles
+Zur Vermeidung von Fehlern bei der Referenzierung von Ressourcen in Bundles sollte eine einheitliche Referenzierung genutzt werden. Das bedeutet, dass absolute und relative Referenzierung nicht gemischt werden sollte. Zur Eindeutigkeit und besseren Lesbarkeit wird empfohlen, durchgehend absolute Referenzen zu verwenden.
+
+Folgendes Beispiel zeigt eine fehlerhafte Referenzierung:
+
+[source,xml]
+----
+<fullUrl value="urn:uuid:bc329f24-3d65-4286-bf06-b54dd6cad655" />
+   <resource>
+      <Composition>
+       ...
+       <section>
+         <reference value="Patient/123" /> <!-- relative Referenzierung, welche sich nicht auflösen lässt -->
+      </section>
+----
+
+Folgend ein korrigiertes Beispiel:
+
+[source,xml]
+----
+<fullUrl value="urn:uuid:bc329f24-3d65-4286-bf06-b54dd6cad655" />
+   <resource>
+      <Composition>
+       ...
+       <section>
+         <reference value="urn:uuid:63ad09fb-ef03-418d-855b-d561d0e2a8fc" /> <!-- ebenfalls eindeutige urn:uuid Referenzierung -->
+      </section>
+----
+
+Alternativ ein korrektes Beispiel für relative Referenzierung:
+
+[source,xml]
+----
+<fullUrl value="http://pvs.praxis.local/fhir/Practitioner/129ce0ed-b427-49c3-907c-14bc1438cbcf" />
+   <resource>
+      <Composition>
+       ...
+       <section>
+         <reference value="Patient/ec897375-8fce-4ebc-8059-80c851e4c8b2" /> <!-- fullURL ist als URL-Schema aufgebaut, relative Referenz kann aufgelöst werden -->
+      </section>
+----
+
+
+Die Referenz "Patient/123" kann nicht aufgelöst werden, da die Umgebende Composition-Ressource keine fullUrl besitzt, die eine base-URL enthält, wonach aufgelöst werden kann.
+
+==== Format von fullURLs
+fullURLs müssen entweder als URL-Schema oder als URN-Schema angegeben werden. Wenn das URL-Schema verwendet wird, muss dieses nach dem link:https://hl7.org/fhir/R4/references.html#regex[Regex für FHIR-URLs] aufgebaut sein. Folgende Hinweise sind zu beachten:
+
+* URLs haben das Format "http(s)://<domain>/<resourceType>/<id>".
+* URNs haben das Format "urn:uuid:<uuid>".
+
+Folgendes Beispiel zeigt eine **ungültige** URL-Referenz:
+
+[source,xml]
+----
+<fullUrl value="www.pvs.praxis.local/fhir/Practitioner/bc329f24-3d65-4286-bf06-b54dd6cad655" /> <!-- ungültige URL, da das Schema fehlt -->
+<fullUrl value="urn:uuid:1" /> <!-- ungültige urn, da keine gültige UUID -->
+----
+
+Gültige Referenzen:
+
+[source,xml]
+----
+<fullUrl value="https://pvs.praxis.local/fhir/Practitioner/bc329f24-3d65-4286-bf06-b54dd6cad655" /> <!-- Korrekte URL nach https://hl7.org/fhir/R4/references.html#regex -->
+<fullUrl value="urn:uuid:4b7e4c01-6ee6-43ee-b527-61a813efa6be" /> <!-- Korrekte UUID nach RFC4122 -->
+----
+
+==== Ressourcen ohne .id
+Ressourcen, die in Bundles enthalten sind, müssen eine .id besitzen. Dies ist notwendig, um die Ressourcen eindeutig referenzieren und identifizieren zu können. Daher müssen diese angegeben werden auch wenn das Datenmodell keine Kardinalität von 1..1 für das Feld .id vorsieht.
+
+Im folgenden Beispiel fehlt die .id in der Ressource:
+
+[source,xml]
+----
+<fullUrl value="http://pvs.praxis.local/fhir/Practitioner/bc329f24-3d65-4286-bf06-b54dd6cad655" />
+        <resource>
+            <Practitioner xmlns="http://hl7.org/fhir">
+                <name> <!-- fehlende .id -->
+                ...
+            </Practitioner>
+----
+
+Beispiel für korrekte Angabe der .id:
+
+[source,xml]
+----
+<fullUrl value="http://pvs.praxis.local/fhir/Practitioner/bc329f24-3d65-4286-bf06-b54dd6cad655" />
+        <resource>
+            <Practitioner xmlns="http://hl7.org/fhir">
+                <id value="bc329f24-3d65-4286-bf06-b54dd6cad655" />
+                <name>
+                ...
+            </Practitioner>
+----
+
 
 == Tools und Hinweise zu FHIR
 

diff --git a/docs_sources/erp_fhir_infos-source.adoc b/docs_sources/erp_fhir_infos-source.adoc
@@ -38,6 +38,7 @@ Durchgängige Beispieldatensätze von der Verordnung und qualifizierter Signatur
 === Referenzierung von FHIR-Objekten in Bundles
 Der FHIR-Standard definiert wie Ressourcen in einem Bundle referenziert werden sollen. Siehe hierzu link:https://hl7.org/fhir/R4/references.html[Referezen] und link:http://hl7.org/fhir/R4/bundle.html[Bundles].
 
+==== Übereinstimmung von id und fullUrl
 Bei Verwendung von relativer Referenzierung in Bundles muss darauf geachtet werden, dass die id der fullUrl der Ressource mit der id der Ressource übereinstimmt.
 
 Beispielsweise ist folgende Konstellation ungültig, da der hintere Teil der fullUrl nicht mit der Ressourcen-ID übereinstimmt (b54dd6cad655 ≠ 000000000000):
@@ -50,6 +51,110 @@ Beispielsweise ist folgende Konstellation ungültig, da der hintere Teil der ful
                 <id value="bc329f24-3d65-4286-bf06-000000000000" />
 ----
 
+Hier das korrigierte Beispiel:
+[source,xml]
+----
+<fullUrl value="http://pvs.praxis.local/fhir/Practitioner/bc329f24-3d65-4286-bf06-b54dd6cad655" />
+        <resource>
+            <Practitioner xmlns="http://hl7.org/fhir">
+                <id value="bc329f24-3d65-4286-bf06-b54dd6cad655" />
+----
+
+==== Einheitliche Referenzierung in Bundles
+Zur Vermeidung von Fehlern bei der Referenzierung von Ressourcen in Bundles sollte eine einheitliche Referenzierung genutzt werden. Das bedeutet, dass absolute und relative Referenzierung nicht gemischt werden sollte. Zur Eindeutigkeit und besseren Lesbarkeit wird empfohlen, durchgehend absolute Referenzen zu verwenden.
+
+Folgendes Beispiel zeigt eine fehlerhafte Referenzierung:
+
+[source,xml]
+----
+<fullUrl value="urn:uuid:bc329f24-3d65-4286-bf06-b54dd6cad655" />
+   <resource>
+      <Composition>
+       ...
+       <section>
+         <reference value="Patient/123" /> <!-- relative Referenzierung, welche sich nicht auflösen lässt -->
+      </section>
+----
+
+Folgend ein korrigiertes Beispiel:
+
+[source,xml]
+----
+<fullUrl value="urn:uuid:bc329f24-3d65-4286-bf06-b54dd6cad655" />
+   <resource>
+      <Composition>
+       ...
+       <section>
+         <reference value="urn:uuid:63ad09fb-ef03-418d-855b-d561d0e2a8fc" /> <!-- ebenfalls eindeutige urn:uuid Referenzierung -->
+      </section>
+----
+
+Alternativ ein korrektes Beispiel für relative Referenzierung:
+
+[source,xml]
+----
+<fullUrl value="http://pvs.praxis.local/fhir/Practitioner/129ce0ed-b427-49c3-907c-14bc1438cbcf" />
+   <resource>
+      <Composition>
+       ...
+       <section>
+         <reference value="Patient/ec897375-8fce-4ebc-8059-80c851e4c8b2" /> <!-- fullURL ist als URL-Schema aufgebaut, relative Referenz kann aufgelöst werden -->
+      </section>
+----
+
+
+Die Referenz "Patient/123" kann nicht aufgelöst werden, da die Umgebende Composition-Ressource keine fullUrl besitzt, die eine base-URL enthält, wonach aufgelöst werden kann.
+
+==== Format von fullURLs
+fullURLs müssen entweder als URL-Schema oder als URN-Schema angegeben werden. Wenn das URL-Schema verwendet wird, muss dieses nach dem link:https://hl7.org/fhir/R4/references.html#regex[Regex für FHIR-URLs] aufgebaut sein. Folgende Hinweise sind zu beachten:
+
+* URLs haben das Format "http(s)://<domain>/<resourceType>/<id>".
+* URNs haben das Format "urn:uuid:<uuid>".
+
+Folgendes Beispiel zeigt eine **ungültige** URL-Referenz:
+
+[source,xml]
+----
+<fullUrl value="www.pvs.praxis.local/fhir/Practitioner/bc329f24-3d65-4286-bf06-b54dd6cad655" /> <!-- ungültige URL, da das Schema fehlt -->
+<fullUrl value="urn:uuid:1" /> <!-- ungültige urn, da keine gültige UUID -->
+----
+
+Gültige Referenzen:
+
+[source,xml]
+----
+<fullUrl value="https://pvs.praxis.local/fhir/Practitioner/bc329f24-3d65-4286-bf06-b54dd6cad655" /> <!-- Korrekte URL nach https://hl7.org/fhir/R4/references.html#regex -->
+<fullUrl value="urn:uuid:4b7e4c01-6ee6-43ee-b527-61a813efa6be" /> <!-- Korrekte UUID nach RFC4122 -->
+----
+
+==== Ressourcen ohne .id
+Ressourcen, die in Bundles enthalten sind, müssen eine .id besitzen. Dies ist notwendig, um die Ressourcen eindeutig referenzieren und identifizieren zu können. Daher müssen diese angegeben werden auch wenn das Datenmodell keine Kardinalität von 1..1 für das Feld .id vorsieht.
+
+Im folgenden Beispiel fehlt die .id in der Ressource:
+
+[source,xml]
+----
+<fullUrl value="http://pvs.praxis.local/fhir/Practitioner/bc329f24-3d65-4286-bf06-b54dd6cad655" />
+        <resource>
+            <Practitioner xmlns="http://hl7.org/fhir">
+                <name> <!-- fehlende .id -->
+                ...
+            </Practitioner>
+----
+
+Beispiel für korrekte Angabe der .id:
+
+[source,xml]
+----
+<fullUrl value="http://pvs.praxis.local/fhir/Practitioner/bc329f24-3d65-4286-bf06-b54dd6cad655" />
+        <resource>
+            <Practitioner xmlns="http://hl7.org/fhir">
+                <id value="bc329f24-3d65-4286-bf06-b54dd6cad655" />
+                <name>
+                ...
+            </Practitioner>
+----
+
 
 == Tools und Hinweise zu FHIR