Lab:V3.0.0-B5 FHIR Lab2zorg: verschil tussen versies

Uit informatiestandaarden
Ga naar: navigatie, zoeken
(→‎Search parameters: add _include:iterate)
(→‎FHIR Search parameters)
 
(18 tussenliggende versies door dezelfde gebruiker niet weergegeven)
Regel 144: Regel 144:
 
|}
 
|}
  
−
==== Search parameters ====
+
==== FHIR Search parameters ====
−
The search interaction is performed by an HTTP GET in agreement with the [http://hl7.org/fhir/R4/search.html FHIR specification]. The table below lists search parameters that SHALL be supported for processing by servers and MAY be supported by clients.
+
The search interaction is performed by an HTTP GET in agreement with the [http://hl7.org/fhir/R4/search.html FHIR specification]. The table below lists search parameters for Observation resource that SHALL be supported for processing by servers and clients.
−
For brevity of the table, the column names are not descriptive, hence a short explanation on what each column means:
+
 
−
* FHIR Search Parameter is the name of the parameter. We abuse terminology here, by including {{fhir|$lastn}} in this table, which technically is an operation on Observation.
+
{| style="text-align: left; width: 100%" cellpadding=5px;  
−
* Data type refers to the data type of the value expected for a given parameter in a search request.
 
−
* Description is a short explanation of the purpose of the parameter in the context of this use case.
 
−
* Inclusion determines whether a parameter is required to appear within a single search request. SHALL means that it is mandatory to use this parameter for any search request in this use case. MAY means that it is optional.
 
−
* Repetition indicates whether a parameter may appear once or multiple times within a single search request.
 
−
* Combination logic describes how multiple occurrences of the same parameter are logically combined (AND/OR) when the parameter is repeated within a single search request. For general behavior regarding AND/OR logic, see [[FHIR:V1.0_FHIR_IG_R4#Search_URLs_and_search_parameters|the section about the use of search parameters in the IG.]]
 
−
* FHIR Resource refers to which resource the search parameter applies in this use case.
 
−
In some cases, a column is not applicable to a specific parameter. In that case we use the flag "n/a".
 
−
{| style="text-align: left;" cellpadding=5px;  
 
 
|- style="color: white; background-color: #e7844b;"
 
|- style="color: white; background-color: #e7844b;"
−
! FHIR Search Parameter || Data type || Description || Inclusion || Repetition || Combination logic || FHIR Resource
+
! Variation type || Variation || Permitted values (if limited) || Data type || Description
 +
 
 +
|- style="color: white; background-color: #eda778;"
 +
! colspan="5"  | category
  
 
|- style="background-color: #fcf0e9;"
 
|- style="background-color: #fcf0e9;"
−
| {{fhir|category}} || {{fhir|CodeableConcept}} || Search on laboratory observations (the value is fixed to laboratory) || SHALL || no || n/a || Observation
+
| || || {{fhir|<nowiki>https://terminology.hl7.org/CodeSystem/observation-category|laboratory</nowiki>}} || {{fhir|token}} || Search on laboratory observations.
 +
 
 +
|- style="color: white; background-color: #eda778;"
 +
! colspan="5"  | patient
  
 
|- style="background-color: #fcf0e9;"
 
|- style="background-color: #fcf0e9;"
−
| {{fhir|patient:identifier}} || {{fhir|Identifier}} || Search in a specific patient context || SHALL || no || n/a || Observation
+
| modifier || {{fhir|identifier}} || {{fhir|<nowiki>http://fhir.nl/fhir/NamingSystem/bsn|[BSN]</nowiki>}} || {{fhir|token}} || Search in a specific patient context
 +
 
 +
|- style="color: white; background-color: #eda778;"
 +
! colspan="5"  | code
  
 
|- style="background-color: #fcf0e9;"
 
|- style="background-color: #fcf0e9;"
−
| {{fhir|code}} || {{fhir|CodeableConcept}} || Search on test code (LOINC/NHG) || MAY || yes || with AND/OR || Observation
+
| code system || LOINC || {{fhir|<nowiki>http://loinc.org|[test code]</nowiki>}} || {{fhir|token}} || Search on the LOINC test code
  
 
|- style="background-color: #fcf0e9;"
 
|- style="background-color: #fcf0e9;"
−
| {{fhir|date}} (with prefix {{fhir|gt}}) || {{fhir|dateTime}} || Search on observation date later than the value || MAY || no || n/a || Observation
+
| code system || NHG || {{fhir|<nowiki>https://referentiemodel.nhg.org/tabellen/nhg-tabel-45-diagnostische-bepalingen|[test code]</nowiki>}} || {{fhir|token}} || Search on the NHG test code
 +
 
 +
|- style="color: white; background-color: #eda778;"
 +
! colspan="5"  | date
  
 
|- style="background-color: #fcf0e9;"
 
|- style="background-color: #fcf0e9;"
−
| {{fhir|date}} (with prefix {{fhir|lt}}) || {{fhir|dateTime}} || Search on observation date earlier than the value || MAY || no || n/a || Observation
+
| prefix || {{fhir|gt}} || || {{fhir|date}} || Search on observation date later than the value
  
 
|- style="background-color: #fcf0e9;"
 
|- style="background-color: #fcf0e9;"
−
| {{fhir|$lastn}} || n/a || Search for the most recent observation || MAY || no || n/a || Observation
+
| prefix || {{fhir|lt}} || || {{fhir|date}} || Search on observation date earlier than the value
 +
 
 +
|- style="color: white; background-color: #eda778;"
 +
! colspan="5"  | _include
 +
 
 +
|- style="background-color: #fcf0e9;"
 +
| modifier || {{fhir|iterate}} || || {{fhir|reference}} || Include linked resources iteratively
  
 
|- style="background-color: #fcf0e9;"
 
|- style="background-color: #fcf0e9;"
−
| {{fhir|max}} || {{fhir|positiveInt}} || Search for last n observations. Must be used as a parameter to operation {{fhir|$lastn}} || MAY || no || n/a || Observation
+
| resource || {{fhir|Patient}} || {{fhir|Observation:patient}} || {{fhir|reference}} || Include linked Patient resources in the response bundle
  
 
|- style="background-color: #fcf0e9;"
 
|- style="background-color: #fcf0e9;"
−
| {{fhir|_include}} || {{fhir|Resource}} || Include linked resources (e.g. Specimen, Patient, Organization) in the response bundle || MAY || yes || with AND || Observation
+
| resource || {{fhir|Organization}} || {{fhir|Observation:organization}} || {{fhir|reference}} || Include linked Organization resources in the response bundle
  
 
|- style="background-color: #fcf0e9;"
 
|- style="background-color: #fcf0e9;"
−
| {{fhir|_include:iterate}} || {{fhir|Resource}} || Include linked resources iteratively || MAY || yes || with AND || Observation
+
| resource || {{fhir|Specimen}} || {{fhir|Observation:specimen}} || {{fhir|reference}} || Include linked Specimen resources in the response bundle
  
 
|+ style="align: bottom; caption-side: bottom; text-align: left;" |  
 
|+ style="align: bottom; caption-side: bottom; text-align: left;" |  
 
|}
 
|}
  
−
==== Search examples ====
+
For the Observation search, the parameters {{fhir|category}} and {{fhir|patient:identifier}} SHALL be included within every search request. The parameters {{fhir|code}}, {{fhir|_include}}, and {{fhir|_include:iterate}} can be repeated; {{fhir|code}} supports combination with AND or OR, while {{fhir|_include}} and {{fhir|_include:iterate}} support combination with AND only. In FHIR search, OR logic is used when multiple values are supplied for the same search parameter (comma-separated), meaning a resource matches if any of the values apply. AND logic is used when a search parameter is to be repeated, meaning the resource must satisfy all of the specified conditions.
−
{| class="mw-collapsible mw-collapsed wikitable"
+
 
 +
==== FHIR Operations ====
 +
 
 +
Clients may invoke {{fhir|$lastn}} to retrieve the most recent Observation(s). The parameter {{fhir|max}} can optionally be provided to specify the number of observations to be returned. For more information on {{fhir|$lastn}}, consult [https://build.fhir.org/observation-operation-lastn.html $lastn operation].
 +
 
 +
==== FHIR Search examples ====
 +
 
 +
{| style="text-align: left; width: 100%;" cellpadding=5px;
 +
|- style="color: white; background-color: #e7844b;"
 +
! Examples
 +
 
 +
|- style="color: white; background-color: #eda778;"
 
! Show all laboratory results with test code 14683-7 (LOINC) of the patient with BSN 111222333  
 
! Show all laboratory results with test code 14683-7 (LOINC) of the patient with BSN 111222333  
−
|-
+
 
−
|
+
|- class="mw-collapsible mw-collapsed" style="background-color: #fcf0e9;"
−
<pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7</pre>
+
| <pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7</pre>
−
|}
+
 
−
{| class="mw-collapsible mw-collapsed wikitable"
+
|- style="color: white; background-color: #eda778;"
 
! Show all laboratory results with test code 14683-7 (LOINC) of the patient with BSN 111222333 from 12 March 2022
 
! Show all laboratory results with test code 14683-7 (LOINC) of the patient with BSN 111222333 from 12 March 2022
−
|-
+
 
−
|
+
|- class="mw-collapsible mw-collapsed" style="background-color: #fcf0e9;"
−
<pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7&date=gt2022-12-03</pre>
+
| <pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7&date=gt2022-12-03</pre>
−
|}
+
 
−
{| class="mw-collapsible mw-collapsed wikitable"
+
|- style="color: white; background-color: #eda778;"
−
! Show all laboratory results with test code 14683-7 (LOINC) of the patient with BSN 111222333 between 12 March 2022 and 7 June 2022
+
! Show all laboratory results with test code 14683-7 (LOINC) of the patient with BSN 111222333 between 12 March 2022 and 7 June 2022
−
|-
+
 
−
|
+
|- class="mw-collapsible mw-collapsed" style="background-color: #fcf0e9;"
−
<pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7&date=gt2022-12-03&date=lt2022-07-06</pre>
+
| <pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7&date=gt2022-12-03&date=lt2022-07-06</pre>
−
|}
+
 
−
{| class="mw-collapsible mw-collapsed wikitable"
+
|- style="color: white; background-color: #eda778;"
 
! Show all laboratory results with test code 14683-7 (LOINC) or 3583 (NHG) of the patient with BSN 111222333
 
! Show all laboratory results with test code 14683-7 (LOINC) or 3583 (NHG) of the patient with BSN 111222333
−
|-
+
 
−
|
+
|- class="mw-collapsible mw-collapsed" style="background-color: #fcf0e9;"
−
<pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7,https://referentiemodel.nhg.org/tabellen/nhg-tabel-45-diagnostische-bepalingen|3583</pre>
+
| <pre>GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7,https://referentiemodel.nhg.org/tabellen/nhg-tabel-45-diagnostische-bepalingen|3583</pre>
−
|}
+
 
−
{| class="mw-collapsible mw-collapsed wikitable"
+
|- style="color: white; background-color: #eda778;"
−
! Show the most recent laboratory result with test code 14683-7 (LOINC) of the patient with BSN 111222333
+
! Show the most recent laboratory result with test code 14683-7 (LOINC) of the patient with BSN 111222333
−
|-
+
 
−
|
+
|- class="mw-collapsible mw-collapsed" style="background-color: #fcf0e9;"
−
<pre>GET [base]/Observation/$lastn?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7</pre>
+
| <pre>GET [base]/Observation/$lastn?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7</pre>
−
|}
+
 
−
{| class="mw-collapsible mw-collapsed wikitable"
+
|- style="color: white; background-color: #eda778;"
 
! Show the five most recent laboratory results with test code 14683-7 (LOINC) of the patient with BSN 111222333
 
! Show the five most recent laboratory results with test code 14683-7 (LOINC) of the patient with BSN 111222333
−
|-
+
 
−
|
+
|- class="mw-collapsible mw-collapsed" style="background-color: #fcf0e9;"
−
<pre>GET [base]/Observation/$lastn?max=5&category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7</pre>
+
| <pre>GET [base]/Observation/$lastn?max=5&category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7</pre>
−
|}
+
 
−
{| class="mw-collapsible mw-collapsed wikitable"
+
|- style="color: white; background-color: #eda778;"
 
! Show the most recent laboratory result of the patient with BSN 111222333
 
! Show the most recent laboratory result of the patient with BSN 111222333
−
|-
+
 
−
|
+
|- class="mw-collapsible mw-collapsed" style="background-color: #fcf0e9;"
−
<pre>GET [base]/Observation/$lastn?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333</pre>
+
| <pre>GET [base]/Observation/$lastn?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333</pre>
 +
 
 +
|+ style="align: bottom; caption-side: bottom; text-align: left;" |
 
|}
 
|}
  

Huidige versie van 4 feb 2026 om 16:52


Under construction icon-blue.png This article or section is in the middle of an expansion or major restructuring and is not yet ready for use.
FunctionalTechnicalFunctioneel-Technisch

For an overview of all current documentation see information standard lab exchange main page


1 Introduction

Go to functional design

This is the technical design (TO) for the information standard (IS) Lab2zorg. This TO must be used together with the IS functional design, see functional design Lab2zorg 3.0.0-beta.4. The data exchange format used in this version is: FHIR R4.

1.1 Support

For questions, feedback, or change requests, please contact our support team at Nictiz Servicemanagement.

1.2 Boundaries

This information standard may overlap with other standards related to identification, roles, and geographic classifications, requiring careful alignment to ensure consistency and avoid duplication. For more information, see functional design Lab2zorg 3.0.0-beta.4.

1.3 Prerequisite knowledge

The following background information is required for understanding this TO:

2 Relationships

The diagrams below show the relationships between different FHIR profiles. The arrows indicate an “is referenced in” relationship.

For example, Patient → Laboratory Test means that the Patient is referenced within the Laboratory Test resource.

2.1 Model overview for usecases without the request

FHIR-model-overview-L2Z-SLR-BLR.png

2.2 Model overview for usecase with the request

FHIR-model-overview-L2P-LOA.png

3 Components

HL7 FHIR is used to accommodate the Dutch Clinical Information Models (zibs) used in the IS.

3.1 HL7 FHIR R4

Em.png

Nictiz uses the FHIR Packaging mechanism. This conveniently bundles all profiles, terminology, example material and other conformance resources you need into a single archive, which can be downloaded or installed using the appropriate FHIR tooling. This version of the information standard uses the following packages:

Note: packages use Semantic Versioning. Other versions can be used at will as long as they have the same major.minor number or a minor number higher than the stated version.

3.1.1 Artifacts

The artifacts of the information standard are presented in the following table:

zib FHIR resource FHIR profile
HealthcareProvider Organization nl-core-HealthcareProvider-Organization
HealthProfessional Practitioner nl-core-HealthProfessional-Practitioner
PractitionerRole nl-core-HealthProfessional-PractitionerRole
LaboratoryTestResult Device nl-core-LaboratoryTestResult.Specimen.Source
Observation nl-core-LaboratoryTestResult
Specimen nl-core-LaboratoryTestResult.Specimen
Patient Patient nl-core-Patient
DiagnosticReport lu-LaboratoryTestResult-DiagnosticReport
ServiceRequest lu-OrderData

3.1.2 Examples of FHIR instances

You can find examples of FHIR-instances (filled-in FHIR profiles) in the Nictiz GitHub repository: Lab exchange HL7-mappings repository.

4 Transactions

4.1 Health professional orders lab tests and receives results

4.1.1 Involved actors

Transaction group Transaction Actor System role code FHIR CapabilityStatement
Send laboratory results based on a request Send laboratory results based on a request Client LAB-LAS Lab2Healthcare_Results_SendReceive
Receive laboratory results Server LAB-LAO
Abbreviations: LAB = Laboratorium, LAS = Laboratoriumresultaat antwoord sturend (systeem), LAO = Laboratoriumresultaat antwoord ontvangend (systeem).

4.2 Health professional retrieves lab results

4.2.1 Involved actors

Transaction group Transaction Actor System role code FHIR CapabilityStatement
Retrieve laboratory results (PULL) Retrieve laboratory results request Client LAB-LRR Lab2Healthcare_Results_RetrieveServe
Retrieve laboratory results response Server LAB-LRB
Abbreviations: LAB = Laboratorium, LRR = Laboratoriumresultaat raadplegend (systeem), LRB = Laboratoriumresultaat beschikbaarstellend (systeem).

4.2.2 FHIR Search parameters

The search interaction is performed by an HTTP GET in agreement with the FHIR specification. The table below lists search parameters for Observation resource that SHALL be supported for processing by servers and clients.

Variation type Variation Permitted values (if limited) Data type Description
category
https://terminology.hl7.org/CodeSystem/observation-category|laboratory token Search on laboratory observations.
patient
modifier identifier http://fhir.nl/fhir/NamingSystem/bsn|[BSN] token Search in a specific patient context
code
code system LOINC http://loinc.org|[test code] token Search on the LOINC test code
code system NHG https://referentiemodel.nhg.org/tabellen/nhg-tabel-45-diagnostische-bepalingen|[test code] token Search on the NHG test code
date
prefix gt date Search on observation date later than the value
prefix lt date Search on observation date earlier than the value
_include
modifier iterate reference Include linked resources iteratively
resource Patient Observation:patient reference Include linked Patient resources in the response bundle
resource Organization Observation:organization reference Include linked Organization resources in the response bundle
resource Specimen Observation:specimen reference Include linked Specimen resources in the response bundle

For the Observation search, the parameters category and patient:identifier SHALL be included within every search request. The parameters code, _include, and _include:iterate can be repeated; code supports combination with AND or OR, while _include and _include:iterate support combination with AND only. In FHIR search, OR logic is used when multiple values are supplied for the same search parameter (comma-separated), meaning a resource matches if any of the values apply. AND logic is used when a search parameter is to be repeated, meaning the resource must satisfy all of the specified conditions.

4.2.3 FHIR Operations

Clients may invoke $lastn to retrieve the most recent Observation(s). The parameter max can optionally be provided to specify the number of observations to be returned. For more information on $lastn, consult $lastn operation.

4.2.4 FHIR Search examples

Examples
Show all laboratory results with test code 14683-7 (LOINC) of the patient with BSN 111222333 
GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7
Show all laboratory results with test code 14683-7 (LOINC) of the patient with BSN 111222333 from 12 March 2022 
GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7&date=gt2022-12-03
Show all laboratory results with test code 14683-7 (LOINC) of the patient with BSN 111222333 between 12 March 2022 and 7 June 2022 
GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7&date=gt2022-12-03&date=lt2022-07-06
Show all laboratory results with test code 14683-7 (LOINC) or 3583 (NHG) of the patient with BSN 111222333 
GET [base]/Observation?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7,https://referentiemodel.nhg.org/tabellen/nhg-tabel-45-diagnostische-bepalingen|3583
Show the most recent laboratory result with test code 14683-7 (LOINC) of the patient with BSN 111222333 
GET [base]/Observation/$lastn?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7
Show the five most recent laboratory results with test code 14683-7 (LOINC) of the patient with BSN 111222333 
GET [base]/Observation/$lastn?max=5&category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333&code=http://loinc.org|14683-7
Show the most recent laboratory result of the patient with BSN 111222333 
GET [base]/Observation/$lastn?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory&patient:identifier=http://fhir.nl/fhir/NamingSystem/bsn|111222333

4.3 Health professional sends lab results to other health professional

4.3.1 Involved actors

Transaction group Transaction Actor System role code FHIR CapabilityStatement
Send laboratory results (PUSH) Send laboratory results Client LAB-LRS Lab2Healthcare_Results_SendReceive
Receive laboratory results Server LAB-LRO
Abbreviations: LAB = Laboratorium, LRS = Laboratoriumresultaat sturend (systeem), LRO = Laboratoriumresultaat ontvangend (systeem).
Overgenomen van "https://informatiestandaarden.nictiz.nl/index.php?title=Lab:V3.0.0-B5_FHIR_Lab2zorg&oldid=289554"