EU Health Data API
1.0.0-ballot - ballot 150

EU Health Data API, published by HL7 Europe. This guide is not an authorized publication; it is the continuous build for version 1.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/euridice-org/eu-health-data-api/ and changes regularly. See the Directory of published versions

Resource Access

Overview

Resource access provides query and read access to individual clinical FHIR resources. This is a parallel path to FHIR Document Exchange.

A vaccination registry that serves Immunization resources, or a medication system that serves MedicationStatement resources, uses resource access without necessarily producing complete priority documents. Systems declare which resources they support.

Resource access for resources that also appear within FHIR Documents (e.g., Conditions referenced in a Patient Summary) is permitted but not required.

Data models for resource access inherit from HL7 Europe Core. This path corresponds to Resource Interoperability Profiles in the Xt-EHR D8.1 conformance framework, aligned with the Xt-EHR Logical Models.

Actors

  • Resource Access Provider (server): Provides resource query capabilities
  • Resource Consumer (client): Queries resources

See Actors and Transactions for detailed actor groupings.

This version of the IG defines resource search and read access. How resources are supplied to a Resource Access Provider is outside its scope. See Resource Exchange Patterns for background and possible future approaches.

Specifications

This IG aligns with:

Data type-specific implementation guides MAY extend the required search patterns and search parameters for the resources in their domain. For example, the MADO implementation guide may define additional search requirements for ImagingStudy and DiagnosticReport in the Imaging Results priority category.

Sequence Diagram

sequenceDiagram
    participant Consumer as Resource Consumer
    participant Provider as Resource Access Provider

    Consumer->>Provider: GET /Condition?patient=123
    Provider-->>Consumer: Bundle of Conditions

    Consumer->>Provider: GET /Observation?patient=123&category=vital-signs
    Provider-->>Consumer: Bundle of Observations

Supported Resources

Following International Patient Access (IPA), Resource Access Providers are not required to support all clinical resources. Servers MAY choose which resources to implement based on their capabilities, use cases, and the regulatory context.

Servers declare which resources they support in their CapabilityStatement (see Capability Discovery). Clients MAY check the server's CapabilityStatement to discover available resources before making requests.

See the Resource Access Provider CapabilityStatement and Resource Consumer CapabilityStatement for detailed capability declarations.

Core Resources

Resource Access uses SMART App Launch 2.2 FHIR resource scopes selected for the endpoint's authorization flow: interactive Patient or Clinician Access uses the applicable patient/ or user/ scopes, and Backend Services uses applicable system/ scopes. These are SMART scopes, not generic FHIR scopes or IUA transaction scopes. Core IUA defines no API-specific scope vocabulary; the IPA and PDQm interactions on this page are not IUA MHD transactions and have no IUA MHD transaction scopes. IUA deployments apply their selected authorization policy to these interactions. See Authorization.

In the regulatory context of EHDS, the following resources represent individual data entries included in the priority data categories, so should be made available for read/search access if the system claims support for the corresponding priority data category. Data models inherit from HL7 Europe Core. Required search parameters are from HL7 International Patient Access (IPA) version 1.1.0, supplemented by IHE-QEDm where IPA does not define them.

Resources by priority data category

The definitions below summarize each resource's data model and required search parameters. The normative requirements are in the Resource Access Provider CapabilityStatement.

Patient

DocumentReference

Practitioner

  • Priority data categories: All
  • Data model: Practitioner (EU Core)
  • Search parameters: This is not a patient-scoped resource, so there is no requirement for Resource Access Providers to support Search, only Read.

Organization

  • Priority data categories: All
  • Data model: Organization (EU Core)
  • Search parameters: This is not a patient-scoped resource, so there is no requirement for Resource Access Providers to support Search, only Read.

Condition

  • Priority data categories: Patient Summary
  • Data model: Condition (EU Core)
  • Search parameters: As described at IPA CapabilityStatement: Condition and QEDm 2:3.44. Resource Access Providers are required to support searching by patient, as long as the Resource Consumer provides at least an id value for the Patient resource.

AllergyIntolerance

MedicationRequest

MedicationStatement

Immunization

MedicationDispense

  • Priority data categories: ePrescription and eDispensation
  • Data model: Not included in EU Core. Refer to MedicationDispense: MPD
  • Search parameters: Not included in IPA or QEDm. As this is a patient-scoped resource, Resource Access Providers are required to support searching by patient, as long as the Resource Consumer provides at least an id value for the Patient resource.

Observation

DiagnosticReport

  • Priority data categories: Medical Test Results; Imaging Results
  • Data model: DiagnosticReport (EU Core)
  • Search parameters: As described at QEDm 2:3.44 (not included in IPA). Resource Access Providers are required to support searching by patient and category, all of patient, category, and code, or all of patient, category, and date. For imaging reports, the MADO implementation guide may define additional search requirements.

ImagingStudy

  • Priority data categories: Imaging Results
  • Data model: Not included in EU Core. Refer to ImagingStudy: General from HL7 Europe Imaging Report
  • Search parameters: Not included in IPA or QEDm. As this is a patient-scoped resource, Resource Access Providers are required to support searching by patient, as long as the Resource Consumer provides at least an id value for the Patient resource. The MADO implementation guide may define additional search requirements.

Encounter

  • Priority data categories: Discharge Reports
  • Data model: Not included in EU Core. Refer to Encounter (HDR)
  • Search parameters: As described in QEDm 2:3.44. Resource Access Providers are required to support searching by patient or patient and date.

This is a core subset of resources for ballot. Ballot feedback is requested on whether this set is appropriate. See Open Issue #9.

This IG does not currently define requirements for advanced search features such as the :not modifier, _include/_revinclude, or chained parameters. Ballot feedback is requested. See Open Issue #13.

Example Queries

These examples use search combinations that providers support when they support the corresponding resource type. Additional filters depend on the capabilities declared by the server.

GET /AllergyIntolerance?patient=123
GET /Condition?patient=123
GET /Observation?patient=123&category=vital-signs&date=ge2024-01-01
GET /DiagnosticReport?patient=123&category=LAB
GET /MedicationRequest?patient=123

Derived Resources

Derived resources SHOULD include a reference to their source, which may be a DocumentReference or a FHIR Document Bundle (Bundle.type = 'document').

{
  "resourceType": "Provenance",
  "target": [{"reference": "Observation/123"}],
  "entity": [{
    "role": "source",
    "what": {"reference": "DocumentReference/abc"}
  }]
}

{
  "resourceType": "Provenance",
  "target": [{"reference": "Observation/123"}],
  "entity": [{
    "role": "source",
    "what": {"reference": "Bundle/abc"}
  }]
}

The IHE mXDE profile is an informative reference for extracting resources from documents while maintaining provenance. This IG does not require conformance to mXDE.

References