2. FHIR IG
2.1. Introduction
This IG describes a patient use case in the context of the information standard "Image Availability" (Dutch: Beeldbeschikbaarheid or BBS), version 1.0.0-alpha.2. The information standard Image Availability as published by Nictiz does not yet include a patient use case, this may change in the future. Up until then, the patient use case will be published by MedMij.
This IG is a technical counterpart of the functional design. The FHIR version used for this IG is R4 (4.0.1).
2.2. Actors involved
| Actor | System | FHIR CapabilityStatement | |||
|---|---|---|---|---|---|
| Name | Description | Name | Description | Name | Description |
| Patient | The user of a personal healthcare environment | PHR (Document Consumer) | Personal health record | CapabilityStatement Retrieve image and report (timeline) | FHIR client requirements |
| Healthcare provider | The user of a XIS | XIS (Document Responder) | Healthcare information system | CapabilityStatement Serve image and report (timeline) | FHIR server requirements |
Table 1: Actors
2.3. Boundaries and relationships
This FHIR IG includes use cases for the exchange of images and reports between healthcare providers (e.g. hospitals) and patients (e.g. in a PHR setting).
This IG assumes that a PHR is able to make a connection to the right XIS that contains the patient's information. It does not provide information on finding the right source system nor does it provide information about security. These infrastructure and interface specifications are described in the MedMij Afsprakenstelsel. In particular, each transaction is performed in the context of a specific authenticated patient, which has been established using the authentication mechanisms outlined in the MedMij Afsprakenstelsel (also see the MedMij FHIR IG by Nictiz), i.e. via an OAuth2 token. Each XIS gateway is required to perform filtering based on the patient associated with the context for the request, so only the records associated with the authenticated patient are returned. For this reason, search parameters should not be included for patient identification.
2.4. Relating FHIR (profiles) to its functional counterpart
The BBS FHIR IG, section 5.3 describes the (intended) mapping between metadata, FHIR (DocumentReference) and the datasets in ART-DECOR. In this FHIR IG, we incorporate the aforementioned functional mapping provided by Nictiz BBS. This mapping has resulted in the bbs-DocumentReference profile.
2.5. Identifiers
There are several identifiers that play a role in the exchange of images and reports. The following table gives an overview of all these identifiers, and how they are related to each other.
| Identifier | Source | Definition | FHIR DocumentReference element |
|---|---|---|---|
| Document Unique ID | Nationale IHE MetaData Set (2024), ihexds-dataelement-29 | The globally unique identifier of a document in XDS, assigned by the document source. This identifier is stable during data exchange and is not generated by the XDS document repository. It is used for identification, version control and deduplication. For an imaging study manifest, the Document Unique ID shall be the same as the SOP Instance UID of the corresponding KOS document. |
.masterIdentifier |
| Report Information Identification Number | Nictiz BBS dataset (1.0.0-alpha.2), bbs-dataelement-100 | The globally unique id of a report of the imaging study in a XIS, used for synchronization and identification of the report. In an XDS context, this identifier could be equal to the Document Unique ID of the report. In DICOM, the Study or Series Instance UID MAY be used as Report Information Identification Number. |
.masterIdentifier |
| Image Information Identification Number | Nictiz BBS dataset (1.0.0-alpha.2), bbs-dataelement-784 | The globally unique id of an imaging study manifest in a PACS (Picture Archiving and Communication System) or VNA (Vendor Neutral Archive). In an XDS context, this identifier refers to the KOS document that describes the set of images within the study. The KOS document is a representation of the imaging study manifest, and is a separate document with its own Document Unique ID (namely its SOP Instance UID). In DICOM, the Study or Series Instance UID MAY be used as Image Information Identification Number. |
.masterIdentifier |
| Accession Number | DICOM (0008,0050); Nationale IHE MetaData Set (2024), ihexds-dataelement-117; MedMij dataset, bbs-medmij-dataelement-3 |
A locally unique record number generated by the RIS that identifies an imaging procedure request created by the RIS in response to a clinical order. It links together the imaging study with its corresponding reports, images, and KOS documents. Moreover, it makes searching on imaging study level possible. Note that if a KOS document is shared or exchanged, the same Accession Number SHALL be present in the metadata attribute ReferenceIdList, as well as the corresponding FHIR DocumentReference resource. |
.context.related |
| Study Instance UID | DICOM (0020,000D); Nationale IHE MetaData Set (2024), ihexds-dataelement-117; MedMij dataset, bbs-medmij-dataelement-4 |
The globally unique DICOM identifier of the imaging study upon which the imaging report is based, assigned by the modality or PACS. All images within an imaging study are implicitly linked to each other with this identifier. Each KOS document contains exactly one Study Instance UID according to IHE WIA. Note that if a KOS document is shared or exchanged, the same Study Instance UID SHOULD be present in the metadata attribute ReferenceIdList, as well as the corresponding FHIR DocumentReference resource. |
.context.related |
| Series Instance UID | DICOM (0020,000E) | The globally unique DICOM identifier of a single series that is part of the study identified by the Study Instance UID, and that contains the referenced object instance(s) (such as individual images). It is used to identify and organize related DICOM objects that are part of the same imaging series. | |
| SOP Instance UID | DICOM (0008,0018) | The globally unique DICOM identifier of a SOP instance (i.e. an individual DICOM object), which is an instantiation of a certain SOP class. Each SOP instance may contain a single image, multiple images or no image at all. | |
| SOP Class UID | DICOM (0008,0016) | The globally unique DICOM identifier of a Service-Object Pair (SOP) class. Each SOP class is defined by the union of a DICOM service and data object, and its definition contains the rules and semantics which may restrict the use of the service. Table 9 lists the SOP classes that need to be supported. |
Table 2: Identifiers relevant in the context of images and reports
Note the following:
- The cardinality of
DocumentReference.masterIdentifieris1..1. If a XIS wants to provide additional identifiers (e.g. a report identifier assigned in the EHR), theDocumentReference.identifiercan be used. - If the Accession Number is known, it SHALL be conveyed in all DocumentReference resources that refer to the corresponding images and reports. In particular, this ensures that images and reports that belong to the same imaging study, are linked together.
- When encoding a DICOM UID (e.g. Study Instance UID) in an Identifier datatype, use the
.systemurn:dicom:uid, and prefix the.valuewith urn:oid:.
2.6. Use cases
The use cases in this IG are based as much as possible on the specifications described in the BBS FHIR IG, section 5.3, namely IHE MHD and WIA. Note however, that QIDO-RS (which is mentioned in the WIA specification) is currently not in scope.
2.6.1. Use case: Retrieve Image and Report in personal health environment
The Nictiz BBS FHIR IG splits the transactions in different use cases, for reasons of convenience. Seen from the perspective of a patient using a PHR, retrieval of images and reports from a healthcare provider is a related activity performed in one action. Therefore, this IG bundles the BBS use cases as one.
2.6.1.1. Query Timeline Data (MHD ITI-67)
Based on Use case 3: Query Timeline Data (Raadplegen Tijdlijn Data) in the Nictiz BBS FHIR IG, see ITI-67 for further details.
The ITI-67 transaction is used to find available documents for a patient, based on a search on DocumentReference.
| Transaction group | Transaction | Actor | System role |
|---|---|---|---|
| Image and report timeline (PULL) | Retrieve image and report timeline | Patient (using a PHR) | MM-1.0-BR-FHIR |
| Image and report timeline (PULL) | Serve image and report timeline | Healthcare provider (using a XIS) | MM-1.0-BB-FHIR |
Table 3: Transactions within sub use case Query Timeline Data
2.6.1.1.1. PHR: request message
The PHR executes an HTTP search against the DocumentReference endpoint of the XIS using the following URL:
GET [base]/DocumentReference{?<query>}
The <query> represents a series of encoded name-value pairs representing the filter for the query. The search parameters listed in the table below SHALL be supported by both PHR and XIS.
| Image Availability search parameter | Description | FHIR search parameter | Examples |
|---|---|---|---|
| availabilityStatus | Search on the status of the DocumentReference. | status |
Retrieve all DocumentReference resources that refer to an approved document. GET [base]/DocumentReference?status=current |
| mimeType | Search on the MIME type of the document. | contenttype |
Retrieve all DocumentReference resources that refer to a report in PDF format. GET [base]/DocumentReference?contenttype=application/pdf Retrieve all DocumentReference resources that refer to an imaging study available as DICOM KOS document. GET [base]/DocumentReference?contenttype=application/dicom |
Table 4: Supported search parameters for ITI-67
Since only approved documents are to be exchanged, the PHR SHALL always include the search parameter status with value current in their request:
GET [base]/DocumentReference?status=current{&<additional parameters>}
Other search parameters can be found in the ITI-67 Request Message specification. The PHR MAY supply all query parameters listed there, with the exception of the patient and patient.identifier search parameters, as patient identification is done differently in the MedMij context (i.e. via an OAuth2 token).
The XIS MAY be capable of processing some or all query parameters listed there. Note that this is a deviation from the ITI-67 specification, in which the XIS SHALL be capable of processing all listed query parameters. However, support of all these query parameters was deemed to pose a disproportionate implementation burden for the XIS, and is therefore not enforced here.
See ITI-67 Request Message for further details.
2.6.1.1.2. XIS: response message
The XIS returns an HTTP Status code appropriate to the processing as well as a Bundle of the matching DocumentReference resources. Based on the value of DocumentReference.category it can be derived whether each respective DocumentReference refers to a report or an image (and hence, in what way the subsequent ITI-68 request should be handled). Other elements, such as .content.attachment.contentType and .content.format, also indicate whether the DocumentReference concerns a report or an image. The table below illustrates some of the possible values (i.e. code-system pairs) in the DocumentReference for reports and images, but it is not meant to be comprehensive.
| FHIR element | Image | Report (PDF) | Report (DICOM) |
|---|---|---|---|
.category |
IMAGES (urn:oid:1.3.6.1.4.1.19376.1.2.6.1) |
REPORTS (urn:oid:1.3.6.1.4.1.19376.1.2.6.1) |
REPORTS (urn:oid:1.3.6.1.4.1.19376.1.2.6.1) |
.content.attachment.contentType |
application/dicom or application/dicom+json | application/pdf | application/dicom or application/dicom+json |
.content.format |
1.2.840.10008.5.1.4.1.1.88.59 (http://dicom.nema.org/resources/ontology/DCMUID) |
Any code from http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem in ValueSet FormatCodes |
1.2.840.10008.5.1.4.1.1.88.59 (http://dicom.nema.org/resources/ontology/DCMUID) |
.context.event[modality] |
Any code from http://dicom.nema.org/resources/ontology/DCM in ValueSet ModalityCombined |
Empty or any code from http://dicom.nema.org/resources/ontology/DCM in ValueSet ModalityCombined |
Any code from http://dicom.nema.org/resources/ontology/DCM in ValueSet ModalityCombined, but often code OT |
Table 5: Possible DocumentReference element values for reports and images
See ITI-67 Response Message for further details.
2.6.1.2. Retrieve Imaging Report (MHD ITI-68)
Based on Use case 4: Retrieve Imaging Report (Raadplegen Verslag) in the Nictiz BBS FHIR IG, see ITI-68 for further details.
| Transaction group | Transaction | Actor | System role |
|---|---|---|---|
| Image and report (PULL) | Retrieve image and report | Patient (using a PHR) | MM-1.0-BR-FHIR |
| Image and report (PULL) | Serve image and report | Healthcare provider (using a XIS) | MM-1.0-BB-FHIR |
Table 6: Transactions within sub use case Retrieve Imaging Report
2.6.1.2.1. PHR: request message
The PHR sends an HTTP GET request to the XIS server to retrieve the imaging report content referenced by a DocumentReference in DocumentReference.content.attachment.url.
The PHR SHALL provide an HTTP Accept header to indicate the preferred MIME type, such that the XIS can provide the imaging report requested in an encoding other than the encoding indicated in the DocumentReference.content.attachment.contentType. The XIS SHALL support the Accept header application/pdf, irrespective of the value of .contentType.
The PHR MAY supply a MIME type in the Accept header other than application/pdf or the MIME type indicated in DocumentReference.content.attachment.contentType. Support for such headers by the XIS is optional.
See ITI-68 Request Message for further details.
2.6.1.2.2. XIS: response message
The XIS returns an HTTP Status code appropriate to the processing. When the requested imaging report is returned, the XIS SHALL respond with HTTP Status Code 200, and the imaging report SHOULD use a correct content type based on the Accept header supplied in the request by the PHR. This MAY include CDA, PDF, or other structured or unstructured formats originating from an EHR.
If the XIS is unable to format the imaging report in a content type listed in the Accept header, it SHALL respond with HTTP Status Code 406.
See ITI-68 Response Message for further details.
2.6.1.3. Retrieve Images (MHD ITI-68 and WADO-RS RAD-107)
Based on Use case 5: Retrieve Images (Raadplegen Beeld) in the Nictiz BBS FHIR IG, see ITI-68 and WADO-RS Retrieve (RAD-107), section 4.107 for further details.
The retrieval of images consists of two consecutive steps, namely the ITI-68 transaction, which retrieves the imaging study manifest content referenced by a DocumentReference in DocumentReference.content.attachment.url (i.e. the DICOM KOS document), and the RAD-107 transaction, which retrieves the individual (image) instances (i.e. the SOP instances) based on the contents of the KOS document. Seen from the perspective of the patient using a PHR, these two transactions are performed in one action.
| Transaction group | Transaction | Actor | System role |
|---|---|---|---|
| Image and report (PULL) | Retrieve image and report | Patient (using a PHR) | MM-1.0-BR-FHIR |
| Image and report (PULL) | Serve image and report | Healthcare provider (using a XIS) | MM-1.0-BB-FHIR |
Table 7: Transactions within sub use case Retrieve Images
2.6.1.3.1. PHR: request message (MHD ITI-68)
The PHR sends an HTTP GET request to the XIS server to retrieve the imaging study manifest content referenced by a DocumentReference in DocumentReference.content.attachment.url.
The PHR SHALL provide an HTTP Accept header to indicate the preferred MIME type, such that the XIS can provide the imaging study manifest requested in an encoding other than the encoding indicated in the DocumentReference.content.attachment.contentType. The table below indicates which MIME types as value of the Accept header SHALL be supported by the XIS relative to the .contentType present in the DocumentReference for which the PHR requests the content. In particular, the XIS has to support reformatting a DICOM KOS document (with .contentType equal to application/dicom) into the DICOM JSON Model (with .contentType equal to application/dicom+json).
The PHR MAY supply a MIME type in the Accept header other than those indicated by the table below or the MIME type indicated in DocumentReference.content.attachment.contentType. Support for such headers by the XIS is optional.
.contentType (ITI-67 Response) |
Accept header (ITI-68 Request) |
|---|---|
| application/dicom | application/dicom |
| application/dicom | application/dicom+json |
| application/dicom+json | application/dicom+json |
Table 8: Mapping between content type and supported Accept headers
See ITI-68 Request Message for further details.
2.6.1.3.2. XIS: response message (MHD ITI-68)
The XIS returns an HTTP Status code appropriate to the processing. When the requested imaging study manifest is returned, the XIS SHALL respond with HTTP Status Code 200, and the imaging study manifest SHOULD use a correct content type based on the Accept header supplied in the request by the PHR. The imaging study manifest SHOULD contain references to the relevant images following the WADO-RS format.
If the XIS is unable to format the imaging study manifest in a content type listed in the Accept header, it SHALL respond with HTTP Status Code 406.
See ITI-68 Response Message for further details.
2.6.1.3.3. PHR: request message (WADO-RS RAD-107)
The WADO-RS Retrieve request (RAD-107) is used to retrieve individual (image) instances. For each (image) instance the PHR wants to retrieve, it executes an HTTP GET against the WADO-RS endpoint of the XIS using the following URL:
GET [WadoRsEndpoint]/studies/[StudyInstanceUID]/series/[SeriesInstanceUID]/instances/[SOPInstanceUID]{/rendered}
Note the following:
- The required
[StudyInstanceUID],[SeriesInstanceUID]and[SOPInstanceUID]unique identifier values can be found in the DICOM KOS document, which is obtained via the ITI-68 Retrieve Document transaction. In Table 2, the corresponding DICOM tags are listed. Note however, that the SOP Instance UID of an individual instance which is referenced by the KOS document can be found in DICOM tag(0008,1155)(Referenced SOP Instance UID) within the KOS document. - By default, the request returns binary DICOM instances, while adding
/renderedto the request results in rendered instances, e.g. in JPEG format (also see Table 10).
Instead of constructing the above URL from scratch by searching all these identifier values from various locations within the KOS document, DICOM tag (0008,1115) (Referenced Series Sequence) provides a structured way to access this information. This sequence contains one or more referenced image series. Each item in the sequence corresponds to a specific series and contains:
- Retrieve URL
(0008,1190) - A sequence of referenced instances (Referenced SOP Sequence
(0008,1199)), each containing:- Referenced SOP Class UID
(0008,1150) - Referenced SOP Instance UID
(0008,1155)
- Referenced SOP Class UID
To simplify the construction of the WADO-RS request, the Retrieve URL (0008,1190) can be used, as it attains the value
[WadoRsEndpoint]/studies/[StudyInstanceUID]/series/[SeriesInstanceUID]
for each series. To create the WADO-RS request with which the image (i.e. SOP instance) is retrieved, the PHR would then only need to append the value of the corresponding Referenced SOP Instance UID (0008,1155) as follows:
[RetrieveURL]/instances/[SOPInstanceUID]
This approach allows the PHR to iterate over all items in the KOS document in the Referenced Series Sequence (0008,1115).
Note however, that this approach is only possible if the Retrieve URL (0008,1190) is present in the KOS document, which might not be the case as it is optional. If it is not present, the PHR instead has to construct the WADO-RS request for each SOP instance from scratch by searching the relevant DICOM identifiers values in the KOS document, as mentioned before.
The table below indicates the minimal set of SOP classes that SHALL be supported. If, for a certain series in the sequence, a SOP Class UID is present in DICOM tag (0008,1150) other than those specified below, the PHR MAY still retrieve the corresponding image, but is not required to do so.
| SOP Class Name | SOP Class UID | Description | Corresponding modality |
|---|---|---|---|
| Computed Radiography (CR) Image Storage | 1.2.840.10008.5.1.4.1.1.1 | Digitalized conventional X-ray images, often used in older systems. | CR |
| Digital X-Ray Image Storage – For Presentation | 1.2.840.10008.5.1.4.1.1.1.1 | Modern digital X-ray images, successor of Computed Radiography (CR) Image Storage. | DX |
| Digital Mammography X-Ray Image Storage – For Presentation | 1.2.840.10008.5.1.4.1.1.1.2 | Specialized X-ray images for digital mammography. | MG |
| Computed Tomography (CT) Image Storage | 1.2.840.10008.5.1.4.1.1.2 | Standard CT images. | CT |
| Enhanced Computed Tomography (CT) Image Storage | 1.2.840.10008.5.1.4.1.1.2.1 | Enhanced CT images with multi-frame structure, recommended to be future-proof. | CT |
| Ultrasound Multi-frame Image Storage | 1.2.840.10008.5.1.4.1.1.3.1 | Dynamic ultrasound images (cine-loops). | US |
| Magnetic Resonance (MR) Image Storage | 1.2.840.10008.5.1.4.1.1.4 | Standard MRI images, supported by all systems. | MR |
| Enhanced Magnetic Resonance (MR) Image Storage | 1.2.840.10008.5.1.4.1.1.4.1 | Multi-frame MRI images with extensive metadata, used by modern MRI scanners. | MR |
| Ultrasound Image Storage | 1.2.840.10008.5.1.4.1.1.6.1 | Static 2D ultrasound images, often used in almost all ultrasound examinations. | US |
| Secondary Capture Image Storage | 1.2.840.10008.5.1.4.1.1.7 | Digital photos or screenshots, e.g. from non-DICOM devices. | SC |
| X-Ray Angiographic Image Storage | 1.2.840.10008.5.1.4.1.1.12.1 | Angiographic images. | XA |
| X-Ray Radiofluoroscopic Image Storage | 1.2.840.10008.5.1.4.1.1.12.2 | Dynamic X-ray images, such as swallow study videos. | RF |
| Nuclear Medicine Image Storage | 1.2.840.10008.5.1.4.1.1.20 | Images of gamma cameras used in nuclear medicine (not in radiology), important for functional imaging (e.g. thyroid, skeleton). | NM |
| Video Endoscopic Image Storage | 1.2.840.10008.5.1.4.1.1.77.1.1.1 | Endoscopic images. | ES |
| Encapsulated PDF Storage | 1.2.840.10008.5.1.4.1.1.104.1 | Used to store PDF documents as DICOM objects, e.g. reports and attachments. | OT |
| Positron Emission Tomography (PET) Image Storage | 1.2.840.10008.5.1.4.1.1.128 | PET scan images used in nuclear medicine. | PT |
| Enhanced Positron Emission Tomography (PET) Image Storage | 1.2.840.10008.5.1.4.1.1.130 | Enhanced PET scan images used in nuclear medicine. | PT |
Table 9: Supported SOP classes
The PHR SHALL provide an HTTP Accept header to indicate the preferred MIME type, such that the XIS can provide the (image) instance in the preferred format. The table below indicates which MIME types as value of the Accept header SHALL be supported by the XIS, as well as the corresponding WADO-RS request (both forms) that needs to be executed by the PHR.
| WADO-RS request | Accept header |
|---|---|
GET [RetrieveURL]/instances/[SOPInstanceUID] GET [WadoRsEndpoint]/studies/[StudyInstanceUID]/series/[SeriesInstanceUID]/instances/[SOPInstanceUID] |
application/dicom |
GET [RetrieveURL]/instances/[SOPInstanceUID]/rendered GET [WadoRsEndpoint]/studies/[StudyInstanceUID]/series/[SeriesInstanceUID]/instances/[SOPInstanceUID]/rendered |
image/jpeg |
Table 10: Supported WADO-RS requests
See WADO-RS Retrieve (RAD-107), section 4.107, for further details.
2.6.1.3.4. XIS: response message (WADO-RS RAD-107)
The XIS returns an HTTP Status code appropriate to the processing. When the requested (image) instance is returned, the XIS SHALL respond with HTTP Status Code 200, and the (image) instance SHOULD use a correct content type based on the Accept header supplied in the request by the PHR.
See WADO-RS Retrieve (RAD-107), section 4.107, for further details.