Proposal for Federation Tier with AQL - revised

Status: Release candidate · Version: 0.9.0 · Date: 2026-09-13 · Supersedes: Proposal for Federation Tier with AQL, openEHR Federation Working Group, 2025-08-20 · License: Creative Commons Zero v1.0 Universal (CC0)

Editorial note

This is a working draft circulated for comment. A companion note, Changes from the 2025-08-20 proposal, records what changed since then. This document stands on its own as a specification and does not otherwise narrate that history.

Referenced documents

The following documents and sources informed several design decisions here.

Document Role in the specification

Proposal for Federation Tier with AQL, openEHR Federation WG, 2025-08-20

The proposal this revision builds on. Differences are catalogued in Changes from the 2025-08-20 proposal.

HL7 Intermediaries White Paper

Façade transparency; the four follow-up-routing approaches; de-duplication provenance; unresponsive-server handling; auth conveyance; numbered Conformance Points.

Identity management in a distributed openEHR architecture (Adviesrapport openEHR federatie MPI), I. Schoonbrood, 2026

A proposal for handling patient identity in a distributed openEHR architecture: why a directly identifying identifier should not be stored in EHR_STATUS.subject, how to map identity resolution onto IHE PIXm/PDQm/XCPD/PMIR, and the end-to-end ITI flow.

RSO Zuid-Limburg data (liberation) strategy

The rationale for a distributed CDR architecture in the Netherlands - why data stays under each provider’s control, the benefits for privacy and consent, per-node consent responsibility, and the centralized-vs-distributed gateway trade-off.

HL7 FHIR Hybrid / Intermediary Exchange IG (https://build.fhir.org/ig/HL7/fhir-exchange-routing-ig/)

The passive reverse-proxy pattern

Netherlands - Generic Functions for data exchange (Nuts nl-generic-functions-ig v0.3.0)

The regional alternative binding (Annex B): GF-Localization, GF-Addressing, GF-Identification, GF-Authentication, GF-Authorization, GF-Consent.

1. Summary

This specification adds a Federation Tier to openEHR querying, so that a client can run one query across multiple distributed CDRs as though they were a single repository.

A federation is a virtual repository built from a securely connected group of nodes that hold vendor-neutral, openEHR-modelled health data and expose openEHR Query (AQL) APIs. Clients reach it through the Federation Tier, implemented by one or more gateways.

The Tier is a technically transparent intermediary: a client MUST be able to send it a conformant openEHR AQL query and follow-up requests without knowing it is federated. Transparency covers the whole openEHR ITS-REST surface, read and write, not AQL alone. The parts that are not federated, notably DEMOGRAPHIC and template management, are named in §7a. A gateway MAY also hold federated stored queries itself, which makes a federated query invocable by name (§12.7).

The architecture has three tiers:

  • Application tier - where end-user applications are built (consuming system of the gateway).

  • Federation Tier - the services that connect the nodes as a virtual repository.

  • Node tier - where data is stored and openEHR APIs are published to access it.

The three tiers - centralized and distributed gateway topologies
Figure 1. The three tiers - centralized and distributed gateway topologies. Source: diagrams/federation_three_tiers.puml.

Federation keys on the per-node local ehr_id, and identity resolution happens outside the query:

  • The client SHOULD identify the patient in AQL the openEHR-idiomatic way, via WHERE e/ehr_status/subject/external_ref/id/value = <patientId>

  • Before any query is dispatched, the gateway resolves the patient identifier to a set of {node, local ehr_id} using an identity/localization service outside AQL (proposed binding: IHE PIXm, with XCPD/PMIR as needed; a region MAY use national services such as a record-locator - see Annex B).

  • Consent is a separate question from localization, and is enforced at each node before it releases data (N27, §13.2). Where a deployment has a consent service it MAY also pre-filter non-consented nodes at Step 1, and some regions bundle this into localization. That pre-filter is optional and never replaces the node’s own check.

  • The gateway then dispatches standard, non-federated AQL scoped to each node’s resolved ehr_id, combines the rows, applies federation DISTINCT/ORDER BY, and annotates each row with endpoint provenance. From the combined result the Application tier can interpret results and take follow-up actions, reads and writes, on a specific node.

The ehr_id is all a node needs to be located by. The patient identifier used for resolution is consumed at the gateway and MUST NOT survive into the query it dispatches, and no other directly identifying identifier may appear in that query, its path or its headers (§5.4). This governs the request the gateway composes. A client’s write payload is archetyped clinical content and passes through unmodified.

A single node can belong to more than one federation and can expose more than one ENDPOINT, for example for different connection types. EHR.system_id is a local identifier of the logical EHR-management system in which an EHR was created. Four identifiers circulate in a federation: node_id, endpoint_id, system_id and creating_system_id. Each routes something different. They are defined in § The four identifiers, and §12a fixes which one governs which request.

The rationale for keying on ehr_id and not on subject, and for placing identity resolution outside the federated query, is given in §5.