MedMij:V2020.01/FHIR IG: verschil tussen versies

Uit informatiestandaarden
Naar navigatie springen Naar zoeken springen
(MM-1207: Add syntax highlighting to XML code)
k (Beveiligde "MedMij:V2020.01/FHIR IG": Protect production page from accidental edits ([Bewerken=Alleen beheerders toestaan] (vervalt niet) [Hernoemen=Alleen beheerders toestaan] (vervalt niet)))
 
(12 tussenliggende versies door 5 gebruikers niet weergegeven)
Regel 1: Regel 1:
 
__NUMBEREDHEADINGS__
 
__NUMBEREDHEADINGS__
 
{{DISPLAYTITLE:MedMij FHIR Implementation Guide}}
 
{{DISPLAYTITLE:MedMij FHIR Implementation Guide}}
{{MedMij:Vprepub/Issuebox_FHIR_IG}}
+
{{MedMij:V2020.01/Issuebox_FHIR_IG}}
  
 
[[Bestand:MedMij2.png |link=https://www.medmij.nl/|rechts|Naar medmij.nl]]
 
[[Bestand:MedMij2.png |link=https://www.medmij.nl/|rechts|Naar medmij.nl]]
 
<imagemap>Bestand:Leeswijzer-technisch-banner 03 white.png|center|400px|alt=Afspraken-Functioneel-Technisch   
 
<imagemap>Bestand:Leeswijzer-technisch-banner 03 white.png|center|400px|alt=Afspraken-Functioneel-Technisch   
 
circle 241 216 211 [https://www.medmij.nl/afsprakenstelsel Afsprakenstelsel]                 
 
circle 241 216 211 [https://www.medmij.nl/afsprakenstelsel Afsprakenstelsel]                 
circle 1013 224 212 [[MedMij:Vprepub/Ontwerpen|Functioneel]]                 
+
circle 1013 224 212 [[MedMij:V2020.01/Ontwerpen|Functioneel]]                 
circle 1787 230 212 [[MedMij:Vprepub/FHIR_IG|Technisch]]                 
+
circle 1787 230 212 [[MedMij:V2020.01/FHIR_IG|Technisch]]                 
 
desc none                     
 
desc none                     
 
</imagemap>
 
</imagemap>
Regel 15: Regel 15:
 
----
 
----
 
{|   
 
{|   
! [[Bestand:BGZ_icoon.png |link=MedMij:Vprepub/FHIR_BGZ_2017 |100px|Patient Summary (BgZ)]]  
+
! [[Bestand:BGZ_icoon.png |link=MedMij:V2020.01/FHIR_BGZ_2017 |100px|Patient Summary (BgZ)]]  
 
!  &nbsp;&nbsp;
 
!  &nbsp;&nbsp;
! [[Bestand:Medication_Icoon.png |link=MedMij:Vprepub/FHIR_MedicationProcess|100px |Medication Process]]
+
! [[Bestand:Medication_Icoon.png |link=MedMij:V2020.01/FHIR_MedicationProcess|100px |Medication Process]]
 
!  &nbsp;&nbsp;
 
!  &nbsp;&nbsp;
! [[Bestand:AllergyIntolerance.png |link=MedMij:Vprepub/FHIR_AllergyIntolerance|106px |Allergy Intolerance]]
+
! [[Bestand:AllergyIntolerance.png |link=MedMij:V2020.01/FHIR_AllergyIntolerance|106px |Allergy Intolerance]]
 
!  &nbsp;&nbsp;
 
!  &nbsp;&nbsp;
! [[Bestand:Self-measurements_Icoon.png |link=MedMij:Vprepub/FHIR_VitalSigns|105px |Self-Measurements]]
+
! [[Bestand:Self-measurements_Icoon.png |link=MedMij:V2020.01/FHIR_VitalSigns|105px |Self-Measurements]]
 
! &nbsp;&nbsp;
 
! &nbsp;&nbsp;
! [[Bestand:LabResults@2x.png |link=MedMij:Vprepub/FHIR_LaboratoryResults |100px|Laboratory Results]]
+
! [[Bestand:LabResults@2x.png |link=MedMij:V2020.01/FHIR_LaboratoryResults |100px|Laboratory Results]]
 
! &nbsp;&nbsp;
 
! &nbsp;&nbsp;
! [[Bestand:BgLZ-icon-text.png|link=MedMij:Vprepub/FHIR_BGLZ|105px| BgLZ]]
+
! [[Bestand:BgLZ-icon-text.png|link=MedMij:V2020.01/FHIR_BGLZ|105px| BgLZ]]
 
|}
 
|}
  
 
{|   
 
{|   
! [[Bestand:PDF-A icoon.png|link=MedMij:Vprepub/FHIR_PDFA |100px |PDF/A - Health Documents]]
+
! [[Bestand:PDF-A icoon.png|link=MedMij:V2020.01/FHIR_PDFA |100px |PDF/A - Health Documents]]
 
! &nbsp;&nbsp;
 
! &nbsp;&nbsp;
! [[Bestand:EAfspraak_-_text.png |link=MedMij:Vprepub/FHIR_eAfspraak |98px |eAfspraak - Appointments]]
+
! [[Bestand:EAfspraak_-_text.png |link=MedMij:V2020.01/FHIR_eAfspraak |98px |eAfspraak - Appointments]]
 
! &nbsp;&nbsp;
 
! &nbsp;&nbsp;
! [[Bestand:Huisartsgegevens-met-tekst.png|link=MedMij:Vprepub/FHIR_GP_Data |105px |Huisartsgegevens - GP Data]]
+
! [[Bestand:Huisartsgegevens-met-tekst.png|link=MedMij:V2020.01/FHIR_GP_Data |105px |Huisartsgegevens - GP Data]]
 
! &nbsp;&nbsp;
 
! &nbsp;&nbsp;
! [[Bestand:MedMij-GGZ-63.png|link=MedMij:Vprepub/FHIR_GGZ |105px |GGZ]]
+
! [[Bestand:MedMij-GGZ-63.png|link=MedMij:V2020.01/FHIR_GGZ |105px |GGZ]]
 
! &nbsp;&nbsp;
 
! &nbsp;&nbsp;
! [[Bestand:Beelden_met_EN_tekst.png|link=MedMij:Vprepub/FHIR_Images |105px |Images]]
+
! [[Bestand:Beelden_met_EN_tekst.png|link=MedMij:V2020.01/FHIR_Images |105px |Images]]
 
! &nbsp;&nbsp;
 
! &nbsp;&nbsp;
! [[Bestand:Vragenlijsten_-_EN_dikkere_rand.png|link=MedMij:Vprepub/FHIR_Questionnaire_and_Questionnaire_Response_(Vragenlijsten)|108px| Questionnaire]]
+
! [[Bestand:Vragenlijsten_-_EN_dikkere_rand.png|link=MedMij:V2020.01/FHIR_Questionnaire_and_Questionnaire_Response_(Vragenlijsten)|108px| Questionnaire]]
 
|}
 
|}
  
Regel 49: Regel 49:
  
 
==Scope==
 
==Scope==
The scope of this guide includes requirements to enable PHR and XIS in the Dutch realm to use standardized structured data in a defined inter-organizational transaction. Health is a vast domain. Therefore, MedMij has made scoping choices for its roadmap. MedMij starts with a limited number of medical subdomains but has the vision to elaborate on more domains later. In scope domains are first described in the [[MedMij:Vprepub/Ontwerpen|functional design]] that underlies this technical design.
+
The scope of this guide includes requirements to enable PHR and XIS in the Dutch realm to use standardized structured data in a defined inter-organizational transaction. Health is a vast domain. Therefore, MedMij has made scoping choices for its roadmap. MedMij starts with a limited number of medical subdomains but has the vision to elaborate on more domains later. In scope domains are first described in the [[MedMij:V2020.01/Ontwerpen|functional design]] that underlies this technical design.
  
 
==Background==
 
==Background==
Regel 69: Regel 69:
 
The 'afsprakenstelsel' references the MedMij information standards. In addition, the  MedMij information standards are specified in the context of the 'afsprakenstelsel.' This applies to the implementation guidance of the use cases described in this implementation guide.
 
The 'afsprakenstelsel' references the MedMij information standards. In addition, the  MedMij information standards are specified in the context of the 'afsprakenstelsel.' This applies to the implementation guidance of the use cases described in this implementation guide.
  
For example, all use cases performed in the context of a specific authenticated patient, for which an OAuth2 token has been retrieved using the Authentication mechanisms described in the [https://www.medmij.nl/afsprakenstelsel/ 'afsprakenstelsel']. This token must be passed in each call in the HTTP header named “Authorization”. Each XIS Gateway is required to perform filtering based on the patient associated with the OAuth2 token received for the request so that only the records associated with the authenticated patient are returned.
+
For example, all use cases performed in the context of a specific authenticated patient, for which an OAuth2 token has been retrieved using the Authentication mechanisms described in the [https://www.medmij.nl/afsprakenstelsel/ 'afsprakenstelsel']. This token must be passed in each call in the HTTP header named <code>Authorization</code>. Each XIS Gateway is required to perform filtering based on the patient associated with the OAuth2 token received for the request so that only the records associated with the authenticated patient are returned.
  
 
=Functional design=
 
=Functional design=
[[Bestand:Functioneel-02.png|link=MedMij:Vprepub/Ontwerpen |100px|rechts|Functional design|Go to functional design]]
+
[[Bestand:Functioneel-02.png|link=MedMij:V2020.01/Ontwerpen |100px|rechts|Functional design|Go to functional design]]
  
All use cases described in this implementation guide have a functional counterpart. The functional design pages are written in Dutch. The main overarching wiki page of the functional designs can be found at [[MedMij:Vprepub/Ontwerpen|here]]. From this page, you can link to the specific use case through the patient journey image or the table index. It is possible to link to the specific functional design page from the technical use case pages in this wiki by clicking on the functional circle in the top image.
+
All use cases described in this implementation guide have a functional counterpart. The functional design pages are written in Dutch. The main overarching wiki page of the functional designs can be found at [[MedMij:V2020.01/Ontwerpen|here]]. From this page, you can link to the specific use case through the patient journey image or the table index. It is possible to link to the specific functional design page from the technical use case pages in this wiki by clicking on the functional circle in the top image.
  
 
=Use cases=
 
=Use cases=
Implementation guidance is provided per use case on separate wiki pages. The next section provides implemenation guidance that apply for all use cases. The green circles represent the available use cases. Click on the circle to go to the use case page.  
+
Implementation guidance is provided per use case on separate wiki pages. The next section provides implementation guidance that apply for all use cases. The green circles represent the available use cases. Click on the circle to go to the use case page.  
  
  
 
{|   
 
{|   
! [[Bestand:BGZ_icoon.png |link=MedMij:Vprepub/FHIR_BGZ_2017 |100px|Patient Summary (BgZ)]]  
+
! [[Bestand:BGZ_icoon.png |link=MedMij:V2020.01/FHIR_BGZ_2017 |100px|Patient Summary (BgZ)]]  
 
!  &nbsp;&nbsp;
 
!  &nbsp;&nbsp;
! [[Bestand:Medication_Icoon.png |link=MedMij:Vprepub/FHIR_MedicationProcess|100px |Medication Process]]
+
! [[Bestand:Medication_Icoon.png |link=MedMij:V2020.01/FHIR_MedicationProcess|100px |Medication Process]]
 
!  &nbsp;&nbsp;
 
!  &nbsp;&nbsp;
! [[Bestand:AllergyIntolerance.png |link=MedMij:Vprepub/FHIR_AllergyIntolerance|106px |Allergy Intolerance]]
+
! [[Bestand:AllergyIntolerance.png |link=MedMij:V2020.01/FHIR_AllergyIntolerance|106px |Allergy Intolerance]]
 
!  &nbsp;&nbsp;
 
!  &nbsp;&nbsp;
! [[Bestand:Self-measurements_Icoon.png |link=MedMij:Vprepub/FHIR_VitalSigns|105px |Self-Measurements]]
+
! [[Bestand:Self-measurements_Icoon.png |link=MedMij:V2020.01/FHIR_VitalSigns|105px |Self-Measurements]]
 
! &nbsp;&nbsp;
 
! &nbsp;&nbsp;
! [[Bestand:LabResults@2x.png |link=MedMij:Vprepub/FHIR_LaboratoryResults |100px|Laboratory Results]]
+
! [[Bestand:LabResults@2x.png |link=MedMij:V2020.01/FHIR_LaboratoryResults |100px|Laboratory Results]]
 
! &nbsp;&nbsp;
 
! &nbsp;&nbsp;
! [[Bestand:BgLZ-icon-text.png|link=MedMij:Vprepub/FHIR_BGLZ|105px| BgLZ]]
+
! [[Bestand:BgLZ-icon-text.png|link=MedMij:V2020.01/FHIR_BGLZ|105px| BgLZ]]
 
|}
 
|}
  
 
{|   
 
{|   
! [[Bestand:PDF-A icoon.png|link=MedMij:Vprepub/FHIR_PDFA |100px |PDF/A - Health Documents]]
+
! [[Bestand:PDF-A icoon.png|link=MedMij:V2020.01/FHIR_PDFA |100px |PDF/A - Health Documents]]
 
! &nbsp;&nbsp;
 
! &nbsp;&nbsp;
! [[Bestand:EAfspraak_-_text.png |link=MedMij:Vprepub/FHIR_eAfspraak |98px |eAfspraak - Appointments]]
+
! [[Bestand:EAfspraak_-_text.png |link=MedMij:V2020.01/FHIR_eAfspraak |98px |eAfspraak - Appointments]]
 
! &nbsp;&nbsp;
 
! &nbsp;&nbsp;
! [[Bestand:Huisartsgegevens-met-tekst.png|link=MedMij:Vprepub/FHIR_GP_Data |105px |Huisartsgegevens - GP Data]]
+
! [[Bestand:Huisartsgegevens-met-tekst.png|link=MedMij:V2020.01/FHIR_GP_Data |105px |Huisartsgegevens - GP Data]]
 
! &nbsp;&nbsp;
 
! &nbsp;&nbsp;
! [[Bestand:MedMij-GGZ-63.png|link=MedMij:Vprepub/FHIR_GGZ |105px |GGZ]]
+
! [[Bestand:MedMij-GGZ-63.png|link=MedMij:V2020.01/FHIR_GGZ |105px |GGZ]]
 
! &nbsp;&nbsp;
 
! &nbsp;&nbsp;
! [[Bestand:Beelden_met_EN_tekst.png|link=MedMij:Vprepub/FHIR_Images |105px |Images]]
+
! [[Bestand:Beelden_met_EN_tekst.png|link=MedMij:V2020.01/FHIR_Images |105px |Images]]
 
! &nbsp;&nbsp;
 
! &nbsp;&nbsp;
! [[Bestand:Vragenlijsten_-_EN_dikkere_rand.png|link=MedMij:Vprepub/FHIR_Questionnaire_and_Questionnaire_Response_(Vragenlijsten)|108px| Questionnaire]]
+
! [[Bestand:Vragenlijsten_-_EN_dikkere_rand.png|link=MedMij:V2020.01/FHIR_Questionnaire_and_Questionnaire_Response_(Vragenlijsten)|108px| Questionnaire]]
 
|}
 
|}
 
+
{{NoteBox|1= When considering an implementation of (parts of) BgLZ, please contact [mailto:standaarden@medmij.nl standaarden@medmij.nl].}}
=Use case overarching principles=
+
{{#lst:FHIR:V1.0_FHIR_IG_STU3|OverarchingPrinciples}}
==Content Types and encodings==
+
{{#lst:FHIR:V1.0_FHIR_IG_STU3|FHIRPackages}}
MedMij uses the [https://hl7.org/fhir/http.html#mime-type FHIR RESTful framework]. This framework defines at least three content-types to send/retrieve information:
 
* XML: application/fhir+xml
 
* JSON: application/fhir+json
 
* RDF: text/turtle - Not supported in MedMij
 
 
 
Servers in MedMij SHALL support both XML and JSON, while clients MAY use either format for the request and the response. For the response, servers SHALL support server-driven content negotiation as described in [https://www.hl7.org/fhir/stu3/http.html#mime-type the FHIR specification]. This means that clients can indicate the desired response format using the optional <code>_format=[mimetype]</code> URL parameter, or the acceptable response format(s) using the <code>Accept</code> header. The URL parameter takes precedence over the header. If a client does not request a specific content-type, then it is server discretion to respond using XML or JSON.
 
 
 
FHIR uses UTF-8 for all request and response bodies. Since the [https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.7.1 HTTP specification (section 3.7.1)] defines a default character encoding of ISO-8859-1, requests and responses SHALL explicitly set the character encoding to UTF-8 using the <code>charset</code> parameter of the MIME-type in the <code>Content-Type</code> header. Requests MAY also specify this <code>charset</code> parameter in the <code>Accept</code> header and/or use the <code>Accept-Charset</code> header.
 
 
 
==Use of coded concepts==
 
Coded information is extremely important for interoperability between systems. It enables systems to act on information rather than have humans read everything for interpretation - it enables medication related alerts, exercise encouragements because of weight increase, and many more things. In the HCIMs and profiles, we therefore strive for complete coverage of all possible situations.
 
 
 
However it is likely that unknown codes present themselves in the communication, for example because the sending system has updated its medication codes to a newer version than the receiving system, or because an older record item is coded in a now deprecated way. Therefore, it is vital that the sender includes the semantics of the code in his communication using (CodeableConcept.)[https://hl7.org/fhir/STU3/datatypes.html#coding coding.display] and/or [https://hl7.org/fhir/STU3/datatypes.html#codeableconcept CodeableConcept.text]. Although it might be overkill for the generic profiles to use these fields in closely coupled situations. Within the loosely coupled MedMij context however, systems SHOULD include .display and/or .text for coded data in FHIR instances. Both could be absent for example in historic data or in data acquired without such info from a third party.
 
 
 
===Mapping of coded concepts===
 
Terminology from HCIMs or UCSDs (use case specific datasets) needs to be faithfully applied to the FHIR profiles, but this is not directly possible when the base FHIR resource defines required terminology that bears no direct relationship with the HCIM or UCSD. These cases include, but are not limited to, the FHIR resource elements of datatype 'code' (Patient.gender, status elements, structural type elements, etc.). This datatype always describes FHIR specific terminology, which usually doesn't align with the HCIM/UCSD terminology.
 
 
 
In these cases, a mapping will be provided to explain the relationship between de HCIM/UCSD terminology and the FHIR terminology. This is normally done through a FHIR [https://hl7.org/fhir/STU3/conceptmap.html ConceptMap], which can translate between the terminology used in the HCIM/UCSD, and the terminology that FHIR instances need to adhere to. Usually, the original terminology from the HCIM/UCSD will be communicated as well by adding the extension [https://simplifier.net/resolve?target=simplifier&canonical=http://nictiz.nl/fhir/StructureDefinition/code-specification code-specification] on the same element. This allows unambiguous interpretation on the receiver end.
 
 
 
Example snippet from an [https://simplifier.net/resolve?target=simplifier&canonical=http://nictiz.nl/fhir/StructureDefinition/zib-AllergyIntolerance AllergyIntolerance] where both the FHIR terminology ''high'' and the SNOMED CT ''24484000'' terminology are communicated. The FHIR terminology is obtained from the HCIM terminlogy using ConceptMap [https://simplifier.net/resolve?target=simplifier&canonical=http://nictiz.nl/fhir/ConceptMap/MateVanKritiekZijnCodelijst-to-allergy-intolerance-criticality MateVanKritiekZijnCodelijst-to-allergy-intolerance-criticality]:
 
 
 
<syntaxhighlight lang="xml">
 
<criticality value="high">
 
  <extension url="http://nictiz.nl/fhir/StructureDefinition/code-specification">
 
    <valueCodeableConcept>
 
      <coding>
 
        <system value="http://snomed.info/sct"/>
 
        <code value="24484000"/>
 
        <display value="Severe"/>
 
      </coding>
 
    </valueCodeableConcept>
 
  </extension>
 
</criticality>
 
</syntaxhighlight>
 
 
 
'''Please note''': Unfortunately, FHIR doesn't have a core structured way for indicating which ConceptMaps to use. Instead, mappings are documented in the description of the element in the profile and/or specifically on the mapping description contained in the element.
 
 
 
To retrieve the indicated ConceptMap on Simplifier, the canonical url from the description needs to be used as search term. We are still examining ways to make this more user friendly, for example by using the [https://hl7.org/fhir/STU3/extension-11179-permitted-value-conceptmap.html extension for ConceptMaps], but that does not work unless various third party tooling is updated.
 
 
 
==Use of the reference datatype==
 
FHIR resources act like the internet where resources point to each other through references. The [https://hl7.org/fhir/STU3/references.html#Reference reference datatype] is comparable to web pages pointing to other web pages, scripts and images. Each reference may be either '''internal''' or '''external'''. The datatype supports a display attribute, comparable to a link title in a web page, and an identifier. The identifier acts as a logical reference when the literal reference is not known. Literal references work based on the FHIR logical id, not the identifier, attribute.
 
 
 
{| class="wikitable"
 
|+MedMij constraints on [https://hl7.org/fhir/STU3/references.html#Reference FHIR STU3 reference datatype]
 
! Name !! Flags !! Card. || Type || Description & Constraints
 
|-
 
| Reference || Σ I || || Element || A reference from one resource to another<br/>''+ SHALL have a contained resource if a local reference is provided''<br/>'''+ SHALL have a reference or identifier unless specified otherwise''' *
 
|-
 
|&#160;&#160;&#160;&#160;reference || Σ || 0..1 || string || Literal reference, Relative, internal or absolute '''(not preferred)''' URL
 
|-
 
|&#160;&#160;&#160;&#160;identifier || Σ || 0..1 || Identifier || Logical reference, when literal reference is not known
 
|-
 
|&#160;&#160;&#160;&#160;display || Σ || '''1..1''' || string || Text alternative for the resource
 
|}
 
 
 
In loosely coupled context it is usually good practice to include information rather than have systems progressively retrieve it. When the FHIR servers are in fact a facade on non-FHIR systems, it may not be possible to build external references from the resource id, as non-FHIR systems may not support that concept. Example: a resource for the general practitioner will have an AGB and/or UZI identifier in any information system, the id for the same resource might not be known anywhere. The expectation within MedMij is therefore that the vast majority of references will be based on internal references or identifier.
 
 
 
The basic requirements for using references in MedMij are:
 
 
 
* The ''reference'', if used, SHALL be resolvable
 
** External references SHALL be regarded in the same context as the resource itself. For internal references, this is guaranteed by default. If the current security context is insufficient for retrieving the reference, then additional negotiation for appropriate privileges may be required.
 
** External references are preferably relative as opposed to absolute.
 
* The ''display'' attribute SHALL be used to provide a very short description of the target resource.
 
 
 
Note: there is a known weakness in the Reference datatype for FHIR STU3 which is fixed in FHIR R4. When the reference datatype element could point to multiple types of resources, e.g. Patient.generalPractitioner reference(Organization | Practitioner), you cannot know what type is meant when you only have an identifier for reference. For this reason:
 
 
 
<nowiki>*</nowiki> Note: the Reference datatype SHALL have a reference or identifier unless specified otherwise. There is a known limitation in some of the FHIR STU3 resources where the appropriate reference type is not available. Examples include PractitionerRole which is missing from Encounter.participant (prevents proper context of the attending physician) and Patient which is missing from Media.operator (prevents patient-generated Media). In such cases, an extension will contain the reference of the appropriate type. This leads to slight duplication: the original Reference.display will be duplicated into the Reference.extension.valueReference.display. Systems that do not know about the extension would thus still have access to the regular Reference.display.
 
 
 
* Literal (internal/external) references are preferred over logical references when a choice in resource type is available.
 
 
 
==Relating FHIR profiles with their functional definitions==
 
All profiles have a traceable relationship with their functional counterpart(s) based on the element mapping mechanism in FHIR. This allows to:
 
# define one or more references from a FHIR profile to an external URL where the functional definition can be found
 
# define for each FHIR profile element to which concept ''within'' a functional definition it corresponds
 
 
 
The functional definition(s) underlying the profile can thus be resolved using the [https://hl7.org/fhir/STU3/structuredefinition-definitions.html#StructureDefinition.mapping StructureDefinition.mapping] metadata field of a profile. To relate a FHIR profile field to a concept from the functional description, the concept ID defined in the [https://hl7.org/fhir/STU3/dataelement-definitions.html#DataElement.mapping DataElement.mapping] can be used to look up the concept in the functional definition. It is possible that a single profile element refers concepts from multiple functional descriptions. Simplifier will show an onverview of all the mappings for a FHIR profile on the dedicated 'mappings' tab, together with a clickable URL to the functional definition. In addition, on the 'overview' tab for each field the relevant mapping can be found.
 
 
 
For example, the profile nl-core-address defines a relationship with [https://simplifier.net/NictizSTU3-Zib2017/nl-core-address/~mappings with four functional definitions], one of which is [https://zibs.nl/wiki/AddressInformation-v1.0(2017EN) AddressInformation-v1.0(2017EN)]. This mapping is identified within the profile using 'hcim-addressinformation-v1.0-2017EN'. Looking at the 'Address.city' element in this profile, one of the mappings is defined as 'hcim-addressinformation-v1.0-2017EN:NL-CM:20.5.3'. This reveals that this element implements (amongst others) the concept from the HCIM AddressInformation-v1.0(2017EN) described using ID 'NL-CM:20.5.3'.
 
 
 
==Profile use and declaration==
 
The implementation guides for the various information standards list the profiles to use for the FHIR resources. In the interest of interoperability it is important that, when using said information standard:
 
* Each resource SHALL be a valid instance of the applicable profile. Note that this applies not only to profiles listed directly in the IG, but also to profiles referred from/used by listed profiles.
 
* Each resource SHALL include the canonical URL of this profile in the <code>meta.profile</code> element. The canonical of compatible base or derived profiles MAY be included as well.
 
 
 
==Resource.text or "the narrative"==
 
The FHIR STU3 specification says instances SHOULD contain a human readable summary of the contained data, which can be used as fallback by the receiver. This human readable text is contained in the [https://hl7.org/fhir/STU3/domainresource-definitions.html#DomainResource.text <code>text</code> element] with datatype "[https://hl7.org/fhir/STU3/narrative.html Narrative]". This human readable text is often referred to as "the narrative".
 
 
 
This implementation guide has the following expectations regarding the use of narratives:
 
* Senders SHALL provide a "clinically safe" ([[#"Clinically safe" narratives|see below]]) narrative of status "''extensions''" (preferred) or "''generated''" ([[#Narrative status|see below]]), unless:
 
** The resource does not support narratives. This is the case for resources that do not derive from DomainResource, like Binary.
 
** The resource is contained in another resource.
 
** It is explicitly documented in the information standard to do otherwise.
 
* Receiver SHALL support the narrative. Ignoring the narrative is considered passive support. Support for the narrative SHALL be in accordance with the status and explicitly documented use in the relevant information standard.
 
* Receiver SHALL NOT generically depend on presence of a clinically safe narrative as their only means to present data to users when an explicitly documented use case for status empty or additional exists. Also, using just the narrative you would not expect to produce graphs, support for medication alerts and other functionality.
 
 
 
==="Clinically safe" narratives===
 
Regarding the contents of the narrative, the [https://hl7.org/fhir/STU3/domainresource-definitions.html#DomainResource.text FHIR STU3 spec states] that:
 
<blockquote>The narrative need not encode all the structured data, but is required to contain sufficient detail to make it "clinically safe" for a human to just read the narrative.</blockquote>
 
And for the Narrative datatype:
 
<blockquote>Structured data SHOULD NOT generally contain information of importance to human readers that is omitted from the narrative. Creators of FHIR resources should not assume that systems will render (or that humans will see) data that is not in the narrative.</blockquote>
 
 
 
The decision to what entails "clinically safe" information, is somewhat arbitrary. Guidelines for "clinically safe" inspired by the [https://hl7.org/fhir/STU3/w5.html FHIR W5 report]:
 
* If you only had the narrative: the intention and context should be clear to you.
 
* Who. Patient/subject, performer, author and/or other primary actors. Is this about family history or the actual patient.
 
* What. The topic for the resource is clear.
 
* When. Is this past, present, or future information.
 
* Why. What led up to the event. E.g. Condition, Referral that caused Encounter or Procedure.
 
* Where. Location of the event/action in the resource.
 
* Context. Relevant context as present as presented in the resource. status, Encounter, EpisodeOfCare, Diagnosis, Condition, BodySite.
 
* Rendering every identifier and/or code detail may not be necessary. Resource.text is for human assessment of the situation so emphasis should be on display text, representing identifier/code/system as relevant in the context.
 
   
 
Informal note: Producing a "clinically safe" narrative can be cumbersome. Various reference frameworks like [https://hapifhir.io/hapi-fhir/docs/model/narrative_generation.html HAPI] include a Narrative Generator of some sort.
 
 
 
===Narrative status===
 
   
 
Datatype Narrative [https://hl7.org/fhir/STU3/valueset-narrative-status.html defines different status codes] to indicate the origin of the narrative text. This implementation guide expects the most common use case to be the status "''extensions''", which means that the narrative is generated entirely from the structured data and the extensions used. The reason for this is that most resources can have extension content defined on them. This status can still be used if a particular instance doesn't contain any extensions.
 
 
 
Alternatively, status "''generated''" may be used if the sender did not anticipate inclusion of regular extension content in the narrative.
 
 
 
'''Note''': for both status "''extensions''" and "''generated''", all modifier extensions SHOULD be included in the narrative as they always affect the semantics.
 
 
 
Senders SHOULD NOT use the other possible statuses unless it is explicitly documented why, e.g. in an information standard. Receivers MAY choose to support narratives with status "''additional''", which means that it holds information not contained in the structured data. Receivers - upon rendering narrative with status "''additional''" - SHOULD make it clear to the user that the information is a fragment, and not the entire thing, in some suitable way.
 
 
 
==Search==
 
 
 
===Search URLs and search parameters===
 
Each use case of the various information standards lists the search parameters to use for a client to query the relevant information on a server. Usually, this is done in the form of (a number of) search URL(s), although individual use cases may use some other form if necessary (for example, listing optional parameters). Regarding the search parameters, the following guidelines apply:
 
 
 
* Unless explicitly marked as optional, the listed search parameters are considered the minimum for a request, meaning that:
 
** All stated parameters and modifiers SHALL be supported both by clients and servers.
 
** All stated parameters and modifiers SHALL be used for searching as specified in the information standard.
 
* A client MAY use additional search parameters in the search (such as date-range) not defined in the information standard. These may serve to further constrain the result set.
 
* A server MAY ignore and MAY support additional search parameters. A server SHALL report the applied parameters [https://www.hl7.org/fhir/stu3/search.html#conformance in the self-link] of the response and SHOULD provide additional information about the search process using an OperationOutcome in the search-result Bundle (as an entry with <code>search.mode</code> set to "''outcome''"). A client MAY use the self-link and/or OperationOutcome to inform the user, independently apply these filters to the result set, or take some other action.
 
* A server SHALL reject any search request that contains parameters suffixed by a modifier that the server does '''not''' support for that parameter. For example, if the server supports the name search parameter, but not the :exact modifier on the name, it should reject a search with the parameter <code>name:exact=Bill</code>, using an HTTP <code>400</code> error with an OperationOutcome with a clear error message.
 
* A server SHALL NOT return information that is out of scope for the defined use case or authorization, even if the request by the client is wider than the use case.
 
* Repeating search parameters constitute a logical AND. Repeating search parameter values constitute a logical OR. Where applicable, this will be described further in the implementation guide.
 
* The order of the search parameters is always irrelevant.
 
 
 
General guidance on the use of search parameters can be found [https://www.hl7.org/fhir/stu3/search.html in the FHIR specification].
 
 
 
====Search on date, number or quantity====
 
When a search parameter has a type of date, number or quantity, the request [https://www.hl7.org/fhir/stu3/search.html#prefix uses prefixes] to control the search behavior. Unless explicitly stated otherwise, the minimum set of supported prefixes for these types is <code>eq</code>, <code>gt</code>, <code>lt</code>, <code>ge</code> and <code>le</code>. For example:
 
<pre>GET [base]/Observation?date=ge2019-01-01&date=le2020-01-01</pre>
 
Searches on all Observation resources that have an <code>effective[x]</code> between January 1, 2019 and January 1, 2020.
 
 
 
====The <code>_lastUpdated</code> search parameter====
 
Retrieving information that was added, changed, deleted relative to a date may be done using the search parameter <code>_lastUpdated</code>, which is available for any resource. Using the parameter <code>_lastUpdated</code>, a system may query for data that is ''new'' since a specified date. Any FHIR server is expected to support this parameter. More information can be found in [https://hl7.org/fhir/STU3/search.html#lastUpdated the section on <code>_lastUpdated</code>] in the FHIR specification.
 
 
 
An example search request is shown below.
 
 
 
<pre>GET [base]/Consent?category=http://snomed.info/sct|11291000146105&_lastUpdated=gt2018-10-01</pre>
 
 
 
This search finds all Consent resources with a category SNOMED code 11291000146105 that have been modified since Oct 1, 2018.
 
 
 
===Search results===
 
====Including referenced resources====
 
Servers may not support read interactions, but all references from search results need to be resolvable (see [[#Use of the reference datatype]]). Therefore servers MAY choose to include the referenced resources in the ''searchset'' Bundle, even if the client didn't use any <code>_include</code> parameters. These resources SHALL have <code>Bundle.entry.mode</code> set to "''include''". Servers SHOULD NOT use contained resources for this purpose.
 
 
 
====Paging====
 
Servers MAY use [https://www.hl7.org/fhir/stu3/search.html#count paging] for performance reasons. Client SHALL support this mechanism to prevent loss of information.
 
 
 
== Usage of the <code>id</code> and <code>fullUrl</code> elements in FHIR instances ==
 
 
 
=== <code>id</code> versus <code>identifier</code> ===
 
FHIR recognizes two fields that are used as identifier for instances: <code>id</code> and <code>identifier</code>. Although these are both identifiers, they are unrelated and serve a completely different purpose:
 
* <code>id</code> is the logical identifier, or technical identifier, akin to the id-field in a database. It is used as a unique handle for every instance on a particular server, and is needed to construct the URL to the instance. As such, it is used for referring between resources. The <code>id</code> has no further meaning outside of the server.
 
* <code>identifier</code> is a business identifier, which has a meaning ''outside'' of the server. Examples are a registration number of a healthcare provider, a BSN or social security number for citizens, ISBNs for books, etc. Any instance may have multiple kinds of identifiers.
 
 
 
This section is about the <code>id</code> field and more general about the concept of a logical/technical id to identify instances on a server. The usage of the <code>identifier</code> field, i.e. the business identifier, cannot be described in general terms and will be dictated one a use-case basis by the particular profiles.
 
 
 
=== When is <code>id</code> expected? ===
 
 
 
As stated above, the logical id is meant to uniquely identify instances on a particular server; it is a vital component when using FHIR within a RESTful context. So as a rule of thumb, the <code>id</code> element should always be present when dealing with instances that have a logical id, thus with instances on a server. This means:
 
* Any operation where an existing instance on the server is addressed, like reading or updating, ''needs'' a logical id to target said instance for the URL. In these cases, <code>id</code> field SHALL be populated in both the request and the response, and it SHALL match the id in the URL.
 
* When a client sends a ''new'' instance to a server using a create operation, the <code>id</code> element is ''not'' expected to be present, but the server SHALL populate it in the response. This is because upon sending, these new instances don't exist yet on the server, so a logical id has no meaning. But whenever it is created on the server, it should get a logical id assigned by the server. (Note: it is not strictly prohibited to populate the <code>id</code> field when sending a new instance, but the server SHOULD ignore it).
 
* When a client performs a search on a server, all instances in the returned searchset Bundle SHALL have the <code>id</code> field populated. Note that in some situations, servers might not support logical id's, for example when it is a stateless middleware server that gets its input from a non-FHIR XIS backend. If this is the case ''and'' if the use case doesn't require read support, [[#uuid-as-logical-id|a single use UUID]] or [[#oid-as-logical-id|an OID]] may be used to populate the <code>id</code> field; however, a server SHOULD try its best to populate it with a meaningful value.
 
 
 
=== Logical ids, <code>fullUrl</code>s and references in Bundles ===
 
 
 
There are several FHIR operations, like searching or batch create operations, where multiple instances are placed together in a Bundle. These instances will usually contain references to each other. These internal references cannot be resolved simply by inspecting the <code>id</code> element of every instance; it is not guaranteed that all instances have a logical id. Instead, Bundles allow an <code>entry.fullUrl</code> element for each instance which may be used for references. This is an additional mechanism to the logical id, not a replacement:
 
* The [[#When_is_id_expected.3F|guidelines above]] for populating the <code>id</code> field still apply.
 
* If <code>id</code> is present, <code>fullUrl</code> SHALL correspond with it (see below).
 
 
 
<code>fullUrl</code>s may be RESTful URLs, UUIDs or even OIDs, based on the situation (which may be mixed within the same Bundle):
 
; Instances with a logical id: If an instance can be accessed on the server using RESTful operations, the <code>id</code> of that instance in the Bundle will be populated. The corresponding <code>fullUrl</code> in this case SHALL be the absolute URL to the instance on the server.<p>Instances within the Bundle may use relative references to each other, like they are on the same server. The FHIR machinery specifies how to find the matching instance based on the <code>fullUrl</code>.</p>
 
; Instances without a logical id: When instances are to be created on a server or when the server doesn't support reading individual instances, they don't have a logical id. When these id-less instances need to be referenced from within a Bundle, there are two alternatives:
 
:* <span id="uuid-as-logical-id"></span>UUIDs can be used as single-use ids that will change each time the Bundle is generated. The <code>fullUrl</code> for the instance will be the UUID prefixed with <code><nowiki>urn:uuid:</nowiki></code>, while the <code>id</code> field (if present) is the unprefixed UUID.
 
:* <span id="oid-as-logical-id"></span>OIDs can be used if the instance has an OID-based ''business'' identifier (i.e. the <code>identifier</code> field), like the UZI number of a healthcare provider. The <code>fullUrl</code> will be the OID prefixed with <code><nowiki>urn:oid:</nowiki></code>, while the <code>id</code> field (if present) is the unprefixed OID. However, the use of OIDs as id has some limitations:
 
:** The <code>id</code> has a maximum length of 64 characters, so only OIDs that contain less than 64 characters can be used.
 
:** OID-based id's are expected to be stable, just like RESTful ids. Different Bundle instances SHALL always use the same OID-based ids.
 
: Instances within the Bundle should use the prefixed version of the UUID/OID for referencing.
 
 
 
==== Example ====
 
Consider a client that wants to send a new Observation instance to a server and simultaneously link it to an existing Task instance. This can be done using a transaction Bundle:
 
<syntaxhighlight lang="xml" highlight="7-8,11,23-24,27-28,33-34,41-42" style="max-height:400px; overflow: auto;">
 
<Bundle xmlns="http://hl7.org/fhir">
 
    <!-- Transaction Bundle that will simultaneously create a new instance and update an existing one -->
 
    <type value="transaction"/>
 
   
 
    <!-- A new instance to create -->
 
    <entry>
 
        <!-- The new instance doesn't have a logical id yet, so a temporary UUID is used for references within the Bundle -->
 
        <fullUrl value="urn:uuid:0e855422-b8ef-4247-9443-f3747e78747e"/>
 
        <resource>
 
            <Observation>
 
                <!-- The id field is absent, because the instance doesn't exist yet on the server -->
 
                ...
 
            </Observation>
 
        </resource>
 
    </entry>
 
    <request>
 
        <method value="POST"/>
 
        <url value="Observation"/>
 
    </request>
 
 
 
    <!-- An existing instance to update with a reference to the new instance -->
 
    <entry>
 
        <!-- RESTful URL of existing Task instance -->
 
        <fullUrl value="http://example-xis.com/Task/1234"/>
 
        <resource>
 
            <Task>
 
                <!-- Logical id of the instance, matches the fullUrl -->
 
                <id value="1234"/>
 
                ...
 
                <output>
 
                    ...
 
                    <valueReference>
 
                        <!-- Reference to the fullUrl of the new instance -->
 
                        <reference value="urn:uuid:0e855422-b8ef-4247-9443-f3747e78747e"/>
 
                    </valueReference>
 
                </output>
 
            </Task>
 
        </resource>
 
        <request>
 
            <method value="PUT"/>
 
            <!-- The path on the server, consistent with fullUrl and id -->
 
            <url value="Task/1234"/>
 
        </request>
 
    </entry>
 
</Bundle>
 
</syntaxhighlight>
 
 
 
The server response should then look like:
 
<syntaxhighlight lang="xml" highlight="5-6,9-10,28-29" style="max-height:400px; overflow: auto;">
 
<Bundle xmlns="http://hl7.org/fhir">
 
    <type value="transaction-response"/>
 
   
 
    <entry>
 
        <!-- The newly created instance gets the logical id "5678" from the server -->
 
        <fullUrl value="http://example-xis.com/QuestionnaireResponse/5678"/>
 
        <resource>
 
            <Observation>
 
                <!-- The id matches the fullUrl -->
 
                <id value="5678"/>
 
                ...
 
            </Observation>
 
        </resource>
 
    </entry>
 
    <response>
 
        ....
 
    </request>
 
 
 
    <entry>
 
        <fullUrl value="http://example-xis.com/Task/1234"/>
 
        <resource>
 
            <Task>
 
                <id value="1234"/>
 
                ...
 
                <output>
 
                    ...
 
                    <valueReference>
 
                        <!-- Reference to the relative URL of the created instance may be relative -->
 
                        <reference value="Observation/5678"/>
 
                    </valueReference>
 
                </output>
 
            </Task>
 
        </resource>
 
        <response>
 
            ....
 
        </response>
 
    </entry>
 
</Bundle>
 
</syntaxhighlight>
 
 
 
== Handling errors==
 
Errors in FHIR interactions are usually communicated using the combination of an appropriate HTTP status code in the 4xx-5xx range, and an [https://hl7.org/fhir/STU3/operationoutcome.html OperationOutcome] resource providing more details regarding the error. The OperationOutcome resource contains mandatory elements to indicate the overall type and severity of the error (respectively <code>code</code> and <code>severity</code>) and MAY express the location (using <code>location</code> or <code>expression</code>) and a free-form or coded description of the error (using the <code>diagnostics</code> or <code>detail</code >element). Although these latter elements are not required, their usage is strongly encouraged.
 
 
 
For the most common errors, the expected handling is listed in table [xxx] below. This should be interpreted as a guideline, as the nature of an error is not always unambiguous and various FHIR reference implementations will make different choices. The FHIR specification provides more detail [https://www.hl7.org/fhir/stu3/http.html on error handling in general] and [https://www.hl7.org/fhir/stu3/search.html#errors for search operations specifically].
 
 
 
In general, most FHIR-related errors (in addition to normal HTTP errors related to security, header and content type negotiation issues) will result in one of these HTTP status codes:
 
* 400 Bad Request - resource could not be parsed, search could not be processed or basic FHIR validation rules failed
 
* 401 Not Authorized - the authorization is required for the interaction that was attempted
 
* 404 Not Found - resource type not supported, or not an FHIR endpoint
 
* 422 Unprocessable Entity - the proposed resource violated applicable FHIR profiles or server business rules
 
 
 
{| class="wikitable" 
 
|-
 
! Interaction
 
! Error
 
! Expected action
 
! Example
 
|-
 
| rowspan=2 |All
 
| Invalid authorization
 
|
 
* HTTP 401 Unauthorized
 
* OperationOutcome with <code>code</code> set to "''security''"
 
| [https://informatiestandaarden.nictiz.nl/wiki/MedMij:Vprepub/FHIR_Error_handling_examples#Invalid_authorization Example]
 
|- 
 
| Resource is not supported
 
|
 
* HTTP 404 Not Found
 
* OperationOutcome with <code>code</code> set to "''not-supported''"
 
| [https://informatiestandaarden.nictiz.nl/wiki/MedMij:Vprepub/FHIR_Error_handling_examples#Resource_is_not_supported Example]
 
|-
 
| rowspan=3 |<code>search</code>
 
| No match for the given search parameters
 
| colspan="2" |''This is not considered an error; a normal Bundle of <code>type</code> "''searchset''" is returned containing 0 entry's''
 
|-
 
| Unkown or unsupported search parameter value. This situation applies to non-supported HCIM profiles when the Resource endpoint itself is supported.
 
|
 
* HTTP 200 OK
 
* Empty Bundle of <code>type</code> "''searchset''"
 
* OperationOutcome in Bundle as an entry marked with <code>Bundle.entry.search.mode</code> of "''outcome''"
 
* OperationOutcome with <code>code</code> set to "''not-found''" and <code>severity</code> not set to "''fatal''" or "''error''"
 
| [https://informatiestandaarden.nictiz.nl/wiki/MedMij:Vprepub/FHIR_Error_handling_examples#Unkown_or_unsupported_search_parameter_value Example]
 
|-
 
| Syntactically incorrect parameter
 
|
 
* HTTP 400 Bad Request
 
* OperationOutcome. There are various issue type codes that could be used, depending on the nature of the error
 
| [https://informatiestandaarden.nictiz.nl/wiki/MedMij:Vprepub/FHIR_Error_handling_examples#Syntactically_incorrect_parameter Example]
 
|-
 
| <code>read</code>
 
| Read request with unknown id
 
|
 
* HTTP 404 Not Found
 
* OperationOutcome with <code>code</code> set to "''not-found''"
 
| [https://informatiestandaarden.nictiz.nl/wiki/MedMij:Vprepub/FHIR_Error_handling_examples#Request_on_an_unknown_id Example]
 
|-
 
| <code>update</code>
 
|  No or incorrect Resource id
 
|
 
* HTTP 400 Bad Request
 
* OperationOutcome with <code>code</code> set to "''invalid''"
 
| [https://informatiestandaarden.nictiz.nl/wiki/MedMij:Vprepub/FHIR_Error_handling_examples#No_or_incorrect_Resource_id Example]
 
|-
 
| <code>create</code>/<code>update</code>
 
| Resource syntax or data is incorrect or invalid 
 
|
 
* HTTP 400 Bad Request or HTTP 422 Unprocessable Entity
 
* OperationOutcome with <code>code</code> set to "''invalid''" or preferably a more specific child code.
 
| [https://informatiestandaarden.nictiz.nl/wiki/MedMij:Vprepub/FHIR_Error_handling_examples#Resource_syntax_or_data_is_incorrect_or_invalid Example]
 
|}
 
 
 
=FHIR Packages=
 
MedMij adopts the FHIR Packaging mechanism to support consistent versioning of profiles and related conformance resources such as OperationDefinitions. FHIR Packaging is based on the NPM Packaging mechanism and offers developers a convenient way to include the conformance resources in their favorite IDE. The relevant package version is indicated and linked in the information standards technical design page.
 
 
 
For even more background information:
 
* [https://blog.fire.ly/2017/11/28/versioning-and-canonical-urls/ What is the problem that packaging could address]
 
* [https://simplifier.net/organization/firely/news/55 Introducing the Simplifier FHIR Package Server] (includes what problem packaging addresses)
 
* [https://simplifier.net/organization/firely/news/56 Firely Torinox introduction] (this is one of the tools that's useful for working with FHIR packages)
 
* [https://wiki.hl7.org/index.php?title=FHIR_NPM_Package_Spec The HL7 wiki that outlines the base specification]
 
 
 
{{NoteBox|It is '''not''' required to implement FHIR based information standards using the packaging mechanism. It is still possible to download all or selected resources from Simplifier on as-needed basis. You are however encouraged to invest in dealing with packages.}}
 
 
 
 
=Relevant links=
 
=Relevant links=
 
'''HL7 FHIR specification'''
 
'''HL7 FHIR specification'''
 
* [https://hl7.org/fhir/STU3/index.html HL7 FHIR STU3]
 
* [https://hl7.org/fhir/STU3/index.html HL7 FHIR STU3]
* [https://wiki.hl7.org/index.php?title=FHIR FHIR wiki]
+
* [https://confluence.hl7.org/ HL7 Confluence]
  
 
'''Repository of MedMij FHIR artefacts'''
 
'''Repository of MedMij FHIR artefacts'''
Regel 485: Regel 119:
 
** [https://github.com/Nictiz/Nictiz-STU3-Zib2017 GitHub] (similar to Simplifier.net)
 
** [https://github.com/Nictiz/Nictiz-STU3-Zib2017 GitHub] (similar to Simplifier.net)
  
=Contact=
+
=Contact and support=
  
 
'''MedMij'''
 
'''MedMij'''
Regel 491: Regel 125:
 
W: https://www.medmij.nl  
 
W: https://www.medmij.nl  
  
E: standaarden@medmij.nl
+
E: [mailto:standaarden@medmij.nl standaarden@medmij.nl]
 +
 
 +
T: [tel:+31703173434 +31-70 317 3434]
  
 
'''Nictiz'''
 
'''Nictiz'''
  
 
W: https://www.nictiz.nl
 
W: https://www.nictiz.nl
 +
 +
E: [mailto:hl7@nictiz.nl hl7@nictiz.nl]
  
 
T: [tel:+31703173450 +31-70 317 3450]
 
T: [tel:+31703173450 +31-70 317 3450]
  
'''Feedback on content in open consultation'''
+
'''Relevant information'''
* [https://www.medmij.nl/consultatiedocumenten/ Documentation]
+
* [https://bits.nictiz.nl/projects/MM/ MedMij (MM) project in BITS]
* [https://bits.nictiz.nl/secure/BrowseProjects.jspa#all BITS for issues]
+
** Our portal for questions about MedMij information standards, FHIR profiles, qualifications, implementation advice, etc.
 
+
** [https://www.nictiz.nl/standaardisatie/informatiestandaarden/bits/ Information about BITS (Beheer Informatie- en Terminologie Standaarden)]
'''FHIR Questions and Discussions'''
+
* [https://medmij.nl/informatiestandaarden/consultatiedocumenten/ Consultation documentation]
 
 
 
* [https://chat.fhir.org chat.fhir.org]
 
* [https://chat.fhir.org chat.fhir.org]
 +
** The public channel for FHIR related questions and discussions
  
 
=Release notes=
 
=Release notes=
Release notes can be found on the [[MedMij:Vprepub/Ontwerpen#Release_Notes|functional design page]].
+
Release notes can be found on the [[MedMij:V2020.01/Ontwerpen#Release_Notes|functional design page]].
  
 
=Releases=
 
=Releases=
Regel 514: Regel 152:
 
! Version !! Date !! Notes
 
! Version !! Date !! Notes
 
|-
 
|-
| [[MedMij:Vprepub/FHIR_IG|2020.01]] || 2020-08-11 || Summer release containing fixes for MedMij information standards
+
| [[MedMij:V2020.01/FHIR_IG|2020.01]] || 2020-08-11 || Summer release containing fixes for MedMij information standards
 
|-
 
|-
 
| [[MedMij:V2019.01_FHIR_IG|2019.01]] || 2019-03-11 || Spring release containing fixes for all information standards
 
| [[MedMij:V2019.01_FHIR_IG|2019.01]] || 2019-03-11 || Spring release containing fixes for all information standards

Huidige versie van 22 nov 2022 om 13:35



Naar medmij.nl
AfsprakenstelselFunctioneelTechnischAfspraken-Functioneel-Technisch

Quick links


Patient Summary (BgZ)    Medication Process    Allergy Intolerance    Self-Measurements    Laboratory Results    BgLZ
PDF/A - Health Documents    eAfspraak - Appointments    Huisartsgegevens - GP Data    GGZ    Images    Questionnaire

1 About the IG

This is the technical MedMij FHIR implementation guide based on HL7® FHIR® version STU3.

1.1 Purpose

An implementation guide for making use of FHIR in the Dutch context. This guide is developed specifically for the use of HL7® FHIR® between personal health records(PHR) and healthcare provider systems (XIS). PHR and XIS vendors that participate in MedMij conform to a framework of agreements, in Dutch this is called the 'afsprakenstelsel.' HL7 FHIR, or just 'FHIR', plays an important role among those agreements and is used as a standard to exchange health information between the involved parties. The purpose of this guide is to describe use cases and provide technical guidance on how to implement FHIR in these situations. This guide outlines the FHIR building blocks, or profiles, involved in these use cases. Moreover, this guide provides a textual explanation of these building blocks and describes their relationship and boundaries.

1.2 Scope

The scope of this guide includes requirements to enable PHR and XIS in the Dutch realm to use standardized structured data in a defined inter-organizational transaction. Health is a vast domain. Therefore, MedMij has made scoping choices for its roadmap. MedMij starts with a limited number of medical subdomains but has the vision to elaborate on more domains later. In scope domains are first described in the functional design that underlies this technical design.

1.3 Background

MedMij aims to stimulate electronic information exchange between patients and caregivers. Caregivers generally have access to software applications to help them support their work in treating patients. Software applications for patients are evolving as we speak, but patients typically are not yet enabled to be regarded as a true partner in the care process. MedMij delivers an agreements scheme to enable patients to become that true partner. The section #Afsprakenstelsel describes the relation to this implementation guide.

Information standards have a functional and technical component. The functional part contains definitions of relevant concepts (dataset) and scenario’s that define when to exchange which of those concepts. The technical part translates the functional scenario’s in an exchange format (such as HL7v3 or FHIR). The stakeholders in MedMij have chosen to introduce FHIR as a modern standard to exchange information in MedMij. A dutch factsheet that explains why FHIR is chosen is available on the MedMij website. MedMij delivers a FHIR representation (profiles) for each domain in scope.

The program ‘Registratie aan de bron’ (Data capture at the point of Care) has defined Health and Care Information models (zorginformatiebouwstenen or zibs) for The Netherlands. zibs contain definitions of healthcare concepts. MedMij information standards contain mappings to these zibs. MedMij creates FHIR profiles based on zibs which include mappings to the relevant zib concepts. As a result, the created profiles enable context-free implementation. Therefore, these profiles are applicable in a broader context than the described use cases or the MedMij context. Reuse of these profiles enables interoperability for health information.

1.4 Audience

The main target audience of this implementation guide is software vendors and developers that will implement FHIR as part of electronic information exchange under MedMij. This IG is intended for developers of PHR as well as XIS vendors. Users of this guide are expected to be familiar with the FHIR specification and resource processing. This guide provides links to relevant sections of the FHIR specification. This implementation guide is not intended to be a tutorial on that subject.

1.5 Language

This implementation guide is written in English, even though the majority of the documentation in MedMij is in Dutch. A Dutch translation of this document may become available. However, the English version is and remains leading. The rationale for choosing English is as follows. Implementers in healthcare are in many cases foreign, e.g., through outsourcing or because the company is a multinational. But even if they are Dutch native speakers, the educational tracks, their programming language of choice, and the implementer communities they are part of will largely be based on the English language. In creating the documentation for the target audience, we have received overwhelming preference from the MedMij implementer community for English. English documentation saves them investments and risks in getting a translation agency on a per vendor basis for each version of the documentation, while at the same time not alienating the native Dutch speaking audience. As a side effect it also helps Nictiz in the international realm in discussions with relevant initiatives such as Argonaut (US), Patients Know Best (UK), the Finnish PHR, and the HL7/FHIR community at large.

2 Afsprakenstelsel

Go to Afsprakenstelsel

The 'afsprakenstelsel' references the MedMij information standards. In addition, the MedMij information standards are specified in the context of the 'afsprakenstelsel.' This applies to the implementation guidance of the use cases described in this implementation guide.

For example, all use cases performed in the context of a specific authenticated patient, for which an OAuth2 token has been retrieved using the Authentication mechanisms described in the 'afsprakenstelsel'. This token must be passed in each call in the HTTP header named Authorization. Each XIS Gateway is required to perform filtering based on the patient associated with the OAuth2 token received for the request so that only the records associated with the authenticated patient are returned.

3 Functional design

Go to functional design

All use cases described in this implementation guide have a functional counterpart. The functional design pages are written in Dutch. The main overarching wiki page of the functional designs can be found at here. From this page, you can link to the specific use case through the patient journey image or the table index. It is possible to link to the specific functional design page from the technical use case pages in this wiki by clicking on the functional circle in the top image.

4 Use cases

Implementation guidance is provided per use case on separate wiki pages. The next section provides implementation guidance that apply for all use cases. The green circles represent the available use cases. Click on the circle to go to the use case page.


Patient Summary (BgZ)    Medication Process    Allergy Intolerance    Self-Measurements    Laboratory Results    BgLZ
PDF/A - Health Documents    eAfspraak - Appointments    Huisartsgegevens - GP Data    GGZ    Images    Questionnaire

5 Use case overarching principles

5.1 Content Types and encodings

Unless stated otherwise, the information standards use the FHIR RESTful framework. This framework defines at least three content-types to send/retrieve information:

  • XML: application/fhir+xml
  • JSON: application/fhir+json
  • RDF: text/turtle - Not supported in this context

Servers SHALL support both XML and JSON, while clients MAY use either format for the request and the response. For the response, servers SHALL support server-driven content negotiation as described in the FHIR specification. This means that clients can indicate the desired response format using the optional _format=[mimetype] URL parameter, or the acceptable response format(s) using the Accept header. The URL parameter takes precedence over the header. If a client does not request a specific content-type, then it is server discretion to respond using XML or JSON.

FHIR uses UTF-8 for all request and response bodies. Since the HTTP specification (section 3.7.1) defines a default character encoding of ISO-8859-1, requests and responses SHALL explicitly set the character encoding to UTF-8 using the charset parameter of the MIME-type in the Content-Type header. Requests MAY also specify this charset parameter in the Accept header and/or use the Accept-Charset header.

5.2 Use of coded concepts

5.2.1 Textual description of coded concepts

Coded information is extremely important for interoperability between systems. It enables systems to act on information rather than have humans read everything for interpretation - it enables medication related alerts, exercise encouragements because of weight increase, and many more things. In the HCIMs and profiles, we therefore strive for complete coverage of all possible situations.

However it is likely that unknown codes present themselves in the communication, for example because the sending system has updated its medication codes to a newer version than the receiving system, or because an older record item is coded in a way that now has been deprecated. It is therefore vital that, in addition to the code itself, the sender includes the semantics of the code. Therefore, systems SHOULD include (CodeableConcept).coding.display and/or CodeableConcept.text for coded data in FHIR instances. These fields may only be absent in rare circumstances, for example when dealing with historic data, or in data acquired without such info from a third party.

5.2.2 Code system URIs

A coded value in FHIR is communicated as a combination of a code (in .code) and the canonical URI for the code system from which it was drawn (in .system). Implementers SHALL use the canonical URI that is defined in the FHIR conformance resource. This canonical URI can be found by inspecting the ValueSet that is bound to a coded element in the appropriate FHIR profile.[1]

Please note: it is an error to assume that the OID assigned to a code system can be used to construct its canonical URI. The canonical URI for use in a FHIR context will always be assigned through the conformance resources[2]. It can align with this OID (as a (urn:oid:[oid] URI), but this is not always the case. For example, SNOMED CT is referenced by URL rather than by urn:oid:[oid].

5.2.3 Mapping of coded concepts

Terminology from HCIMs or UCSDs (use case specific datasets) needs to be faithfully applied to the FHIR profiles, but this is not directly possible when the base FHIR resource defines required terminology that bears no direct relationship with the HCIM or UCSD. These cases include, but are not limited to, the FHIR resource elements of datatype code (Patient.gender, status elements, structural type elements, etc.). This datatype always describes FHIR specific terminology, which usually doesn't align with the HCIM/UCSD terminology.

In these cases, a mapping will be provided to explain the relationship between de HCIM/UCSD terminology and the FHIR terminology. This is normally done through a FHIR ConceptMap, which can translate between the terminology used in the HCIM/UCSD, and the terminology that FHIR instances need to adhere to. When the ConceptMap .equivalence is not equal or equivalent, the original terminology from the HCIM/UCSD SHALL be communicated as well using the extension code-specification on the same element. It is recommended to use this extension in other situations as well. This allows unambiguous interpretation on the receiver end.

Example snippet from an AllergyIntolerance where both the FHIR terminology high and the SNOMED CT 24484000 terminology are communicated. The FHIR terminology is obtained from the HCIM terminology using ConceptMap MateVanKritiekZijnCodelijst-to-allergy-intolerance-criticality:

<criticality value="high">
  <extension url="http://nictiz.nl/fhir/StructureDefinition/code-specification">
    <valueCodeableConcept>
      <coding>
        <system value="http://snomed.info/sct"/>
        <code value="24484000"/>
        <display value="Severe"/>
      </coding>
    </valueCodeableConcept>
  </extension>
</criticality>

5.3 Use of the reference datatype

A key feature of FHIR is the ability of resources to reference each other. This is done using the Reference datatype. This datatype supports two modes of referencing:

Literal references, using the .reference element
A relative or absolute REST endpoint containing .id of the referenced resource. In a Bundle context, this may also be a reference to a Bundle.resource.fullUrl.
Logical references, using the .identifier element
Meaning a match on the business identifier (.identifier) for the referenced resource, without specifying where to find the referenced resource. Note: confusingly, although this reference type is called "logical reference", it does not act on the "logical identifier" (.id) of resources.

The resource/profile will usually constrain which resources may be targeted from a given element. For example, Patient.generalPractitioner may point only to an Organization or Practitioner resource, and the nl-core-patient profile further restricts this to the nl-core-organization and nl-core-practitioner profiles[1].

The basic requirements for using references in this context are:

  • Either a literal or logical reference SHALL be specified, unless specified otherwise.
    • Literal references are preferred over logical references when multiple target resource types/profiles may be used[2].
  • Literal references SHALL be resolvable.
    • External references SHALL be regarded in the same context as the resource itself. If the current security context is insufficient for retrieving the reference, then additional negotiation for appropriate privileges may be required.
    • Relative references are preferred over absolute references.
  • A short description of the target resource SHALL be included using the .display element.

Note 1: ^ In some circumstances, the constraints om the target are too strict for the use case and the appropriate resource can't be referenced (examples are Encounter.participant, which cannot reference a PractitionerRole resource to provide context of the attending physician, and Media.operator, which cannot target Patient resources and thus doesn't recognize patient-generated Media). In such cases, the proper reference type is added using an extension within the element that is used to refer the other resource. To aid receiving systems that cannot handle the extension, the sending system SHOULD give as much information as possible in the main element. In the case of the PractitionerRole reference extension, this means that the sending system SHOULD populate the main element with the reference to the Practitioner resource. In most other cases, the sender SHOULD repeat the .display used in the extension in the main element.

Note 2: ^ There is a known weakness in the Reference datatype for FHIR STU3 which is fixed in FHIR R4: if the reference might have more than one type of resource as target, a receiving system cannot know what type is meant when only an identifier is provided.

5.4 Relating FHIR profiles with their functional definitions

All profiles have a traceable relationship with their functional counterpart(s) based on the element mapping mechanism in FHIR. This allows to:

  1. define one or more references from a FHIR profile to an external URL where the functional definition can be found
  2. define for each FHIR profile element to which concept within a functional definition it corresponds

The functional definition(s) underlying the profile can thus be resolved using the StructureDefinition.mapping metadata field of a profile. To relate a FHIR profile field to a concept from the functional description, the concept ID defined in the DataElement.mapping can be used to look up the concept in the functional definition. It is possible that a single profile element refers concepts from multiple functional descriptions. Simplifier will show an overview of all the mappings for a FHIR profile on the dedicated 'mappings' tab, together with a clickable URL to the functional definition. In addition, on the 'overview' tab for each field the relevant mapping can be found.

For example, the profile nl-core-address defines a relationship with with four functional definitions, one of which is AddressInformation-v1.0(2017EN). This mapping is identified within the profile using 'hcim-addressinformation-v1.0-2017EN'. Looking at the Address.city element in this profile, one of the mappings is defined as 'hcim-addressinformation-v1.0-2017EN:NL-CM:20.5.3'. This reveals that this element implements (amongst others) the concept from the HCIM AddressInformation-v1.0(2017EN) described using ID 'NL-CM:20.5.3'.

5.4.1 Absence of the mustSupport flag

The basic notion for any element or extension in a profile, most specifically when it has a mapping to a functional definition, is: provide what you have, and support what you can. At the zib profiling level it is not known what the exact context of use will be. This means that a formal FHIR mustSupport flag would possibly not hold in every imaginable use case. Therefore, mustSupport flags are absent in zib profiles. The exact requirements for the use case at hand should not be inferred from the zib profiles, but from the functional specification that is part of any information standard.

An information standard may provide additional use case or transaction specific profiles, which constrain cardinalities and apply mustSupport as applicable, for extra implementation guidance.

5.5 Profile use and declaration

The implementation guides for the various information standards list the profiles to use for the FHIR resources. A profile is a statement about the rules that this resource was created against. In the interest of interoperability it is important that, when using said information standard:

  • Each resource SHALL be a valid instance of the applicable profile. Note that this applies not only to profiles listed directly in the IG, but also to profiles referred from/used by listed profiles.
  • Each resource SHALL include the canonical URL of this profile in the meta.profile element. The canonical of compatible base or derived profiles MAY be included as well.
  • A receiving system MAY use the stated value of meta.profile for validation, documentation or other purposes.
  • A receiving system MAY use other profiles than stated in meta.profile, e.g. when it has derived, more constrained profiles based on the stated meta.profile. Reasons for additional validation may include protecting the integrity of the receiving system or determination of internal process flow.

5.6 Resource.text or "the narrative"

The FHIR STU3 specification says instances SHOULD contain a human readable summary of the contained data, which can be used as fallback by the receiver. This human readable text is contained in the .text element with datatype Narrative. This human readable text is often referred to as "the narrative".

This implementation guide has the following expectations regarding the use of narratives:

  • Senders SHOULD provide a "clinically safe" (see below) narrative of status extensions (preferred) or generated (see below), unless:
    • The resource does not support narratives. This is the case for resources that do not derive from DomainResource, like Binary.
    • The resource is contained in another resource.
    • It is explicitly documented in the information standard to do otherwise.
  • Receiver SHALL support the narrative. Ignoring the narrative is considered passive support. Support for the narrative SHALL be in accordance with the status and explicitly documented use in the relevant information standard.
  • Receiver SHALL NOT generically depend on presence of a clinically safe narrative as their only means to present data to users when an explicitly documented use case for status empty or additional exists. Also, using just the narrative you would not expect to produce graphs, support for medication alerts and other functionality.

5.6.1 "Clinically safe" narratives

Regarding the contents of the narrative, the FHIR STU3 spec states that:

The narrative need not encode all the structured data, but is required to contain sufficient detail to make it "clinically safe" for a human to just read the narrative.

And for the Narrative datatype:

Structured data SHOULD NOT generally contain information of importance to human readers that is omitted from the narrative. Creators of FHIR resources should not assume that systems will render (or that humans will see) data that is not in the narrative.

The decision to what entails "clinically safe" information, is somewhat arbitrary. Guidelines for "clinically safe" inspired by the FHIR W5 report:

  • If you only had the narrative: the intention and context should be clear to you.
  • Who. Patient/subject, performer, author and/or other primary actors. Is this about family history or the actual patient.
  • What. The topic for the resource is clear.
  • When. Is this past, present, or future information.
  • Why. What led up to the event. E.g. Condition, Referral that caused Encounter or Procedure.
  • Where. Location of the event/action in the resource.
  • Context. Relevant context as present as presented in the resource. status, Encounter, EpisodeOfCare, Diagnosis, Condition, BodySite.
  • Rendering every identifier and/or code detail may not be necessary. Resource.text is for human assessment of the situation so emphasis should be on display text, representing identifier/code/system as relevant in the context.

Informal note: Producing a "clinically safe" narrative can be cumbersome. Various reference frameworks like HAPI include a Narrative Generator of some sort.

5.6.2 Narrative status

Datatype Narrative defines different status codes to indicate the origin of the narrative text. This implementation guide expects the most common use case to be the status extensions, which means that the narrative is generated entirely from the structured data and the extensions used. The reason for this is that most resources can have extension content defined on them. This status can still be used if a particular instance doesn't contain any extensions.

Alternatively, status generated may be used if the sender did not anticipate inclusion of regular extension content in the narrative.

Note: for both status extensions and generated, all modifier extensions SHOULD be included in the narrative as they always affect the semantics.

Senders SHOULD NOT use the other possible statuses unless it is explicitly documented why, e.g. in an information standard. Receivers MAY choose to support narratives with status additional, which means that it holds information not contained in the structured data. Receivers - upon rendering narrative with status additional - SHOULD make it clear to the user that the information is a fragment, and not the entire thing, in some suitable way.

5.7 Search

5.7.1 Search URLs and search parameters

Each use case of the various information standards lists the search parameters to use for a client to query the relevant information on a server. Usually, this is done in the form of (a number of) search URL(s), although individual use cases may use some other form if necessary (for example, listing optional parameters). Regarding the search parameters, the following guidelines apply:

  • Unless explicitly marked as optional, the listed search parameters are considered the minimum for a request, meaning that:
    • All stated parameters and modifiers SHALL be supported both by clients and servers.
    • All stated parameters and modifiers SHALL be used for searching as specified in the information standard.
  • A client MAY use additional search parameters in the search (such as date-range) not defined in the information standard. These may serve to further constrain the result set.
  • A server MAY ignore and MAY support additional search parameters. A server SHALL report the applied parameters in the self link of the response and SHOULD provide additional information about the search process using an OperationOutcome in the search result Bundle (as an entry with search.mode set to outcome). A client MAY use the self link and/or OperationOutcome to inform the user, independently apply these filters to the result set, or take some other action.
  • A server SHALL reject any search request that contains parameters suffixed by a modifier that the server does not support for that parameter. For example, if the server supports the name search parameter, but not the :exact modifier on the name, it should reject a search with the parameter name:exact=Bill, using an HTTP 400 error with an OperationOutcome with a clear error message.
  • A server SHALL NOT return information that is out of scope for the defined use case or authorization, even if the request by the client is wider than the use case.
  • Repeating search parameters constitute a logical AND. Repeating search parameter values constitute a logical OR. Where applicable, this will be described further in the implementation guide.
  • The order of the search parameters is always irrelevant.

General guidance on the use of search parameters can be found in the FHIR specification.

5.7.1.1 Search on date, number or quantity

When a search parameter has a type of date, number or quantity, the request uses prefixes to control the search behavior. Unless explicitly stated otherwise, the minimum set of supported prefixes for these types is eq, gt, lt, ge and le. For example:

GET [base]/Observation?date=ge2019-01-01&date=le2020-01-01

Searches on all Observation resources that have an .effective[x] between January 1, 2019 and January 1, 2020.

5.7.1.2 The _lastUpdated search parameter

Retrieving information that was added, changed, deleted relative to a date may be done using the search parameter _lastUpdated, which is available for any resource. Using the parameter _lastUpdated, a system may query for data that is new since a specified date. Any FHIR server is expected to support this parameter. More information can be found in the section on _lastUpdated in the FHIR specification.

An example search request is shown below.

GET [base]/Consent?category=http://snomed.info/sct|11291000146105&_lastUpdated=gt2018-10-01

This search finds all Consent resources with a category SNOMED code 11291000146105 that have been modified since Oct 1, 2018.

5.7.2 Search results

5.7.2.1 Including referenced resources

Servers may not support read interactions, but all references from search results need to be resolvable (see #Use of the reference datatype). Therefore servers MAY choose to include the referenced resources in the searchset Bundle, even if the client didn't use any _include parameters (example). These resources SHALL have Bundle.entry.mode set to "include". Servers SHOULD NOT use contained resources for this purpose.

The examples page illustrates how servers can provide resolveable references in different situations.

5.7.2.2 Paging

Servers MAY use paging for performance reasons. Client SHALL support this mechanism to prevent loss of information.

5.8 Usage of the .id, .identifier and .fullUrl elements in FHIR instances

5.8.1 .id versus .identifier

FHIR recognizes two fields that are used as identifier for instances: .id and .identifier. Although these are both identifiers, they are unrelated and serve a completely different purpose:

  • .id is the logical identifier, or technical identifier, akin to the id-field in a database. It is used as a unique handle for every instance on a particular server, and is needed to construct the URL to the instance. As such, it is used for referring between resources. The .id has no further meaning outside of the server.
  • .identifier is a business identifier, which usually has a meaning outside of the server. Examples are a registration number of a healthcare provider, a BSN or social security number for citizens, ISBNs for books, etc. Any instance may have multiple kinds of identifiers.

5.8.2 When is .identifier expected?

Systems that use an (internal) stable identifier to track information are encouraged to assign it to the .identifier element of FHIR instances when sending the resource, using a custom identifier .system (e.g. an URL or OID that is under control of the sending organization). Because in HL7v3 (CDA) an identifier can only be composed using OIDs, the .system should preferably be an OID to accommodate compatibility in transformations from FHIR. Especially for resources that are used in information standards that have a HL7v3 (CDA) component, such as the BgZ, GP data and Medication process.

The presence of this element helps receiving systems with re-identification and deduplication of resources, especially when the sender system does not natively support logical ids.

Specific requirements for the usage of .identifier will be dictated on a use case basis by the particular profiles.

5.8.3 When is .id expected?

As stated above, the logical id is meant to uniquely identify instances on a particular server; it is a vital component when using FHIR within a RESTful context. So as a rule of thumb, the .id element should always be present when dealing with instances that have a logical id, thus with instances on a server. This means:

  • When a client reads, updates or otherwise addresses an existing resource on a server, the .id element SHALL be populated in the request and response, and it SHALL match the id in the request URL.
  • When a client sends a new instance to a server using a create operation, the id element is not expected to be present -- these new instances don't exist yet on the server, so a logical id has no meaning. However, the server SHALL assign a logical id and populate the .id element in the response.
    Note: It is not strictly prohibited to populate the .id field when sending a new instance, but the server SHOULD ignore it.
  • When a client performs a search on a server, all instances in the returned searchset Bundle SHOULD have the .id field populated.
    Note: A server SHOULD try its best to create stable ids for the resources it serves. Omitting .id elements is strongly discouraged as it breaks the assumptions about RESTful behavior. However, a server that omits .ids is still considered conformant when the conditions below are met:
    1. The server does not natively support logical ids, for example when it is a stateless middleware server that gets its input from a non-FHIR XIS backend.
    2. And the use case doesn't require read / update / delete / patch support for any of the returned of referenced resources, as stated by the CapabilityStatement for the information standard.
    3. And the server includes all referenced resources in the searchset Bundle (regardless of whether the client asked to do so). These resources refer to each other based on the fullUrl mechanism as described below.

5.8.4 Logical ids, .fullUrls and references in Bundles

There are several FHIR operations, like searching or batch create operations, where multiple instances are placed together in a Bundle. These instances will usually contain references to each other. These internal references cannot be resolved simply by inspecting the .id element of every instance; it is not guaranteed that all instances have a logical id. Instead, Bundles allow an entry.fullUrl element for each instance which may be used for references. This is an additional mechanism to the logical id, not a replacement:

  • The guidelines above for populating the .id field still apply.
  • If .id is present, .fullUrl SHALL correspond with it (see below).

.fullUrls may be RESTful URLs, UUIDs or even OIDs, based on the situation (which may be mixed within the same Bundle):

Instances with a logical id
If an instance can be accessed on the server using RESTful operations, the .id of that instance in the Bundle will be populated. The corresponding .fullUrl in this case SHALL be the absolute URL to the instance on the server.

Instances within the Bundle may use relative references to each other, like they are on the same server. The FHIR machinery specifies how to find the matching instance based on the .fullUrl.

Instances without a logical id
When instances are to be created on a server or when the server doesn't support reading individual instances, they don't have a logical id. When these id-less instances need to be referenced from within a Bundle, there are two alternatives:
  • UUIDs can be used as single-use ids that will change each time the Bundle is generated. The .fullUrl for the instance will be the UUID prefixed with urn:uuid:. [3]
  • OIDs can be used if the instance has an OID-based business identifier (i.e. the .identifier field), like the UZI number of a healthcare provider. The .fullUrl will be the OID prefixed with urn:oid:[3][4].
Instances within the Bundle should use the prefixed version of the UUID/OID for referencing.

5.8.4.1 Example

Consider a client that wants to send a new Observation instance to a server and simultaneously link it to an existing Task instance. This can be done using a transaction Bundle (also see the search results examples page for additional examples):

<Bundle xmlns="http://hl7.org/fhir">
    <!-- Transaction Bundle that will simultaneously create a new instance and update an existing one -->
    <type value="transaction"/>
    
    <!-- A new instance to create -->
    <entry>
        <!-- The new instance doesn't have a logical id yet, so a temporary UUID is used for references within the Bundle -->
        <fullUrl value="urn:uuid:0e855422-b8ef-4247-9443-f3747e78747e"/>
        <resource>
            <Observation>
                <!-- The id field is absent, because the instance doesn't exist yet on the server -->
                ...
            </Observation>
        </resource>
    </entry>
    <request>
        <method value="POST"/>
        <url value="Observation"/>
    </request>

    <!-- An existing instance to update with a reference to the new instance -->
    <entry>
        <!-- RESTful URL of existing Task instance -->
        <fullUrl value="http://example-xis.com/Task/1234"/>
        <resource>
            <Task>
                <!-- Logical id of the instance, matches the fullUrl -->
                <id value="1234"/>
                ...
                <output>
                    ...
                    <valueReference>
                        <!-- Reference to the fullUrl of the new instance -->
                        <reference value="urn:uuid:0e855422-b8ef-4247-9443-f3747e78747e"/>
                    </valueReference>
                </output>
            </Task>
        </resource>
        <request>
            <method value="PUT"/>
            <!-- The path on the server, consistent with fullUrl and id -->
            <url value="Task/1234"/>
        </request>
    </entry>
</Bundle>

The server response should then look like:

<Bundle xmlns="http://hl7.org/fhir">
    <type value="transaction-response"/>
    
    <entry>
        <!-- The newly created instance gets the logical id "5678" from the server -->
        <fullUrl value="http://example-xis.com/QuestionnaireResponse/5678"/>
        <resource>
            <Observation>
                <!-- The id matches the fullUrl -->
                <id value="5678"/>
                ...
            </Observation>
        </resource>
    </entry>
    <response>
        ....
    </request>

    <entry>
        <fullUrl value="http://example-xis.com/Task/1234"/>
        <resource>
            <Task>
                <id value="1234"/>
                ...
                <output>
                    ...
                    <valueReference>
                        <!-- Reference to the relative URL of the created instance may be relative -->
                        <reference value="Observation/5678"/>
                    </valueReference>
                </output>
            </Task>
        </resource>
        <response>
            ....
        </response>
    </entry>
</Bundle>

5.9 Handling errors

Errors in FHIR interactions are usually communicated using the combination of an appropriate HTTP status code in the 4xx-5xx range, and an OperationOutcome resource providing more details regarding the error. The OperationOutcome resource contains mandatory elements to indicate the overall type and severity of the error (respectively .code and .severity) and MAY express the location (using .location or .expression) and a free-form or coded description of the error (using the .diagnostics or .detail element). Although these latter elements are not required, their usage is strongly encouraged.

For the most common errors, the expected handling is listed in the table below. This should be interpreted as a guideline, as the nature of an error is not always unambiguous and various FHIR reference implementations will make different choices. The FHIR specification provides more detail on error handling in general, access denied responses and for search operations specifically.

In general, most FHIR-related errors (in addition to normal HTTP errors related to security, header and content type negotiation issues) will result in one of these HTTP status codes:

  • 400 Bad Request - resource could not be parsed, search could not be processed or basic FHIR validation rules failed
  • 401 Unauthorized - authorization is required for the interaction that was attempted (usually emitted by the authorization server)
  • 403 Forbidden - the server was unable to execute the search, due to an authorization failure (usually emitted by the resource server)
  • 404 Not Found - resource type not supported, or not an FHIR endpoint
  • 422 Unprocessable Entity - the proposed resource violated applicable FHIR profiles or server business rules
Interaction Error Expected action Example
All Not authorized, absent or expired access token
  • HTTP 401 Unauthorized
  • OperationOutcome with .code set to security
Example
Invalid authorization, scope of the access token is not sufficient for the request
  • HTTP 403 Forbidden
  • OperationOutcome with .code set to security
Example
Resource is not supported
  • HTTP 404 Not Found
  • OperationOutcome with .code set to not-supported
Example
search No match for the given search parameters This is not considered an error, but a normal search without results.
Unknown search parameter This is not considered an error. See the guidance in the section on searching.
Syntactically incorrect parameter
  • HTTP 400 Bad Request
  • OperationOutcome. There are various issue type codes that could be used, depending on the nature of the error
Example
Known but unsupported value. This situation applies to non-supported HCIM profiles when the Resource endpoint itself is supported.
  • HTTP 200 OK
  • Empty Bundle of .type searchset
  • OperationOutcome in Bundle as an entry marked with Bundle.entry.search.mode of outcome.
  • OperationOutcome with .code set to not-found and .severity not set to fatal or error.
Example
read Read request with unknown id
  • HTTP 404 Not Found
  • OperationOutcome with .code set to not-found
Example
update No or incorrect Resource id
  • HTTP 400 Bad Request
  • OperationOutcome with .code set to invalid
Example
create/update Resource syntax or data is incorrect, invalid or unsupported
  • HTTP 400 Bad Request or HTTP 422 Unprocessable Entity
  • OperationOutcome with .code set to invalid or preferably a more specific child code.
Example


5.10 CapabilityStatements

Information standards may have a CapabilityStatement that is informative in nature and does not represent the minimum or maximum set of capabilities the client or server should support. Nictiz will strive to provide CapabilityStatements that are as complete as possible, however for the exact set of capabilities the implementation guide of the corresponding information standard should be consulted.

5.11 Referring other resources when sending information

When the client creates/updates a resource on a server, it often needs to reference "secondary" resources which are not the primary focus of the interaction -- e.g. an Observation must indicate its subject using a reference to a Patient resource. The client may refer to existing resources on the server for this, but this is not always possible (for example, the client doesn't know about the existing resource or the server doesn't support the read operation for it). In this case, the client needs to send the secondary resources along with the primary resource in a Bundle, and the server should align these new resources with the ones it already has.

A data conflict may arise if these secondary resources carry details that are not of interest within the particular context of the information standard. For example, the client posts an Observation and sends along a Patient resource containing a different telephone number than the one that is on record at the server side. This change in telephone number is not relevant in this particular context, since the interaction is about creating the Observation.

Unless more specific guidance is given by the information standard, the following guidance applies:

  • Sending secondary resources SHALL only be done when the information standard specifies that a batch or transaction operation is to be used.
  • If so, the client MAY send a bare-bones instance as the secondary resource containing just minimal information, but this SHOULD include the information necessary for the server to match its own copy. The information standard MAY specify which information is minimally needed for such a secondary resource and MAY also restrict the information that is sent in the secondary resource.
  • The client MUST include a Bundle.entry.request for each of the resources in the Bundle, including the secondary resources that are only there for referencing purposes[5]. .request SHOULD be a POST to the appropriate endpoint. As an alternative, PUT MAY be used, but is strongly discouraged; if the client has knowledge on the id of the resource on the server, an absolute URL is strongly preferred.
  • If the server can unequivocally de-duplicate this secondary resource (for example, because the patient is already known from the security context or the healthcare provider is recognized by the UZI number), it MAY choose to ignore the differences of this resource or it MAY incorporate them (see the the section on transactional integity in the FHIR specification). Please note that absence of information should not result in deletion of information on the server, as the client could send a bare-bones instance.
    • If a transaction operation is used and the server chooses to ignore the differences, it SHOULD do so silently by responding with a 200 OK status code for the corresponding Bundle.entry.response.status in the response Bundle.
    • If a batch operation is used and the server chooses to ignore the differences, it SHOULD do so either silently using the mechanism described above, or explicitly by responding with a 422 Unprocessable Entity status code Bundle.entry.response.status to indicate that a business rule prevented the resource from being created (in combination with an OperationOutcome resource).
  • The server SHALL rewrite the references in the primary resource to the resource it already has.

6 FHIR Packages

The information standards maintained by Nictiz adopt the FHIR Packaging mechanism to support consistent versioning of profiles and related conformance resources such as OperationDefinitions. FHIR Packaging is based on the NPM Packaging mechanism and offers developers a convenient way to include the conformance resources in their favorite IDE. The relevant package version is indicated and linked in the information standards technical design page.

Please note that every effort has been made to ensure that the examples contained in the packages are correct and useful, but they are not a normative part of any information standard.

For even more background information:

7 Relevant links

HL7 FHIR specification

Repository of MedMij FHIR artefacts

8 Contact and support

MedMij

W: https://www.medmij.nl

E: standaarden@medmij.nl

T: +31-70 317 3434

Nictiz

W: https://www.nictiz.nl

E: hl7@nictiz.nl

T: +31-70 317 3450

Relevant information

9 Release notes

Release notes can be found on the functional design page.

10 Releases

Version Date Notes
2020.01 2020-08-11 Summer release containing fixes for MedMij information standards
2019.01 2019-03-11 Spring release containing fixes for all information standards
2018.06 2018-10-29 Added GGZ
2018.05 2018-09-24 Added GGZ for open consultation
2018.04 2018-08-29 eAfspraak fase 2
2018.03 2018-05-07 Published BgZ 2017 and GP Data
2018.02 2018-03-29 Added BgZ 2017
2018.01 2018-02-21 Added GP patient data
2017.04 2017-12-18 Added Appointments, Medication, Laboratory results, AllergyIntolerance, Self-measurements
2017.03 2017-11-07 Added PDF/A
2017.02 2017-10-11 Unchanged. No wiki pages created for FHIR
2017.01 2017-10-02 Initial version containing Patient Administration Resources, Patient Summary (BgZ),
  1. Although the canonical URI is not formally defined in the ValueSet, in practical terms it can be found here.
  2. There are exceptions to this, in which case other rules apply, see the FHIR specifications. However, this situation is not expected to occur in the use cases that this IG covers.
  3. 3,0 3,1 Some implementations may choose to populate the .id element with the unprefixed UUID or OID in cases when the .id field is expected, for example in searchset Bundles. The FHIR specification is ambiguous on the requirements to do so. For a long discussion on the topic, see chat.fhir.org.
  4. The use of OIDs as id has some limitations:
    • The .id has a maximum length of 64 characters, so only OIDs that contain less than 64 characters can be used.
    • OID based ids are expected to be stable, just like RESTful ids. Different Bundle instances SHALL always use the same OID based ids.
    • Some objects may have multiple OID based identifiers, like AGB and UZI for practitioners. Which one do you choose? And what happens when the UZI number becomes available after you've already used the AGB as .id?
    • Specifically for HL7 V3 based backends: an HL7 V3 II datatype normally consists of a @root (OID) and an @extension (string). Concatenation of @root and @extension only yields a new OID if @extension is numeric. Other combinations of @root.@extension, may yield a valid .id (pattern [A-Za-z0-9\-\.]{1,64}), but may not be a valid OID. In this case it is no longer possible to create a .fullUrl consistent with the .id based the urn:oid: scheme.
  5. Although Bundle.entry.request is not formally required in FHIR STU3, it is made clear in FHIR R4 that the expected behavior actually is to include it.