FHIR Integration Design: [Programme or solution name]
Solution design for a healthcare interoperability solution built on
HL7 FHIR and IHE profiles: use cases and actors, FHIR version
strategy, resources, profiles and implementation guides, terminology,
IHE ITI profiles (MHD, PIXm, PDQm, IUA, mCSD), SMART App Launch
authorisation, consent and privacy, Bulk Data Access, coexistence with
HL7 Version 2 and CDA, conformance testing and operations. Version
basis: FHIR R5 (5.0.0) as the current published release, FHIR R4
(4.0.1) as the most widely deployed, FHIR R6 still in ballot; IHE ITI
Technical Framework Revision 20.2; US Core 9.0.0; SMART App Launch
2.2.0; Bulk Data Access 3.0.0. Regulatory touchpoints cover the US
ONC/ASTP HTI rules and TEFCA, HIPAA and the EU European Health Data
Space Regulation (EU) 2025/327. Replace every [bracketed] value and
every row marked Example. This is a documentation format, not legal
advice.
Document control
| Field | Value |
|---|
| Document ID | [FHIR-INT-001] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Owner | [@interoperability-architect] |
| Approvers/reviewers | [@clinical-safety-officer], [@privacy-officer], [@security-architect], [@ehr-integration-lead], [@terminology-lead] |
| Organisation and partners | [Health system, HIE, payer, vendor partners] |
| Jurisdictions | [US / EU member state / UK / other] |
| FHIR release and IGs | [R4 4.0.1 with US Core 9.0.0 / R5 5.0.0 with national IG / other] |
| IHE profiles | [MHD, PIXm, PDQm, IUA, mCSD, others], ITI TF Revision [20.2] |
| Regulatory regimes | [HIPAA, HTI rules, TEFCA, EHDS, GDPR, national law] |
| Clinical safety | [Clinical risk management standard and hazard log reference] |
| Classification | [Confidential] |
| Last updated | YYYY-MM-DD |
Approvals
| Role | Name | Decision | Date |
|---|
| Clinical safety officer | [@name] | [Approve / Approve with conditions / Reject] | YYYY-MM-DD |
| Privacy officer or DPO | [@name] | [Decision] | YYYY-MM-DD |
| Security | [@name] | [Decision] | YYYY-MM-DD |
| Architecture board | [@name] | [Decision] | YYYY-MM-DD |
Revision history
| Version | Date | Author | Change summary |
|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft |
| 1.0 | YYYY-MM-DD | [@name] | Example: Approved for regional document sharing pilot |
| 1.1 | YYYY-MM-DD | [@name] | Example: Added bulk export for population health; US Core upgraded |
Contents
1. Use cases and actors
1.1 Use cases
| ID | Use case | Actors | Trigger | Current method | Volume |
|---|
| UC-001 (Example) | Clinician at an emergency department retrieves documents from other hospitals | ED clinician, document registry, other hospitals | Patient registration | Phone and fax | [2,000 queries a day] |
| UC-002 (Example) | Patient uses a third-party app to access their records | Patient, app, EHR FHIR server | Patient consent | Portal download | [n] |
| UC-003 (Example) | Hospital publishes discharge summaries for the GP | Hospital EHR, document repository, GP system | Discharge | Letter by post or HL7 v2 | [n] |
| UC-004 (Example) | Population health team receives monthly bulk extracts | Analytics platform, EHR | Schedule | Database extract | [n] patients |
| UC-005 (Example) | Directory lookup of practitioners and services | Any participant, care services directory | Referral | Spreadsheet | [n] |
| [UC-NNN] | [Use case] | [Actors] | [Trigger] | [Current] | [Volume] |
1.2 Actor and system context
The diagram places every actor from section 1.1 around the platform components described in section 9.2. Internal feeds stay on HL7 Version 2 through the integration engine; external partners reach FHIR and IHE endpoints only through the gateway.
2. Requirements
2.1 Functional requirements
| ID | Requirement | Use case | Acceptance criterion |
|---|
| FR-001 (Example) | Find documents for a patient across participating hospitals | UC-001 | MHD Find Document References returns results from all registries in under [3 seconds] |
| FR-002 (Example) | Resolve the patient's identifiers across organisations | UC-001, UC-003 | PIXm query returns the correct cross-referenced identifiers in test set |
| FR-003 (Example) | Patient-authorised app reads clinical data defined by the national core IG | UC-002 | App passes the IG test kit read scenarios |
| FR-004 (Example) | Discharge summary published within [1 hour] of signing | UC-003 | Document available to GP system in 99 % of cases |
| FR-005 (Example) | Monthly bulk export of defined resource types for a patient group | UC-004 | Export of [n] patients completes within [6 hours] |
| [FR-NNN] | [Requirement] | [UC] | [Criterion] |
2.2 Quality attributes
| ID | Attribute | Requirement | Verification |
|---|
| NFR-001 (Example) | Availability | Clinical query APIs 99.9 % monthly | Monitoring |
| NFR-002 (Example) | Latency | Read of a single resource under [500 ms] at the 95th percentile | Load test |
| NFR-003 (Example) | Security | All access authorised with scoped tokens and audited | Security test, audit review |
| NFR-004 (Example) | Data integrity | No clinical data altered in transformation; codes preserved | Round-trip and terminology tests |
| NFR-005 (Example) | Clinical safety | Hazards assessed and controls verified before go-live | Clinical safety case |
| [NFR-NNN] | [Attribute] | [Requirement] | [Verification] |
2.3 Volumes and sizing
Size the platform from the use case volumes and write the consequence of each number. The figures are a worked example for a regional network.
| ID | Quantity | Example value | Derivation | Design consequence |
|---|
| VOL-001 (Example) | UC-001 document queries a day | 2,000 | Emergency department attendances that need outside records | Input to VOL-002 |
| VOL-002 (Example) | API calls per query | 6 | One token request, one PIXm query, one find, three retrieves on average | 12,000 calls a day from UC-001 |
| VOL-003 (Example) | Peak hour calls | 1,440 | 12 % of 12,000 in the busiest hour | Under one call a second: latency (NFR-002) and registry fan-out, not throughput, drive the design |
| VOL-004 (Example) | Bulk export cohort | 500,000 patients at 400 resources each | Population health cohort definition | 200 million resources a month |
| VOL-005 (Example) | Bulk export size and rate | About 300 GB at 1.5 KB per resource | 200 million times 1.5 KB | Inside the 6-hour window of FR-005: about 9,260 resources a second and 50 GB an hour; export from a read replica with parallel workers, never from the live EHR |
| VOL-006 (Example) | Patient identity records in the MPI | 3,000,000 across 12 organisations | Sum of active patient registers | Matching index and review queue sizing in section 6.3 |
Recompute the derived values whenever an input changes: VOL-002 times VOL-001 gives the daily call count, and the resource count divided by 21,600 seconds gives the export rate.
3. FHIR version and implementation guide strategy
3.1 FHIR release status (checked at hl7.org, October 2026)
| Release | Version | Status | Use in this design |
|---|
| R4 | 4.0.1 (published 2019-10-30) | First release with normative content; the most widely implemented release and the base for most national IGs | [Example: All partner-facing APIs] |
| R4B | 4.3.0 (2022-05-28) | Interim release, limited adoption | [Not used] |
| R5 | 5.0.0 (2023-03-26) | Current published release | [Example: Internal subscriptions pilot only] |
| R6 | 6.0.0-ballot5 (2026-07-17) and 6.0.0-snapshot1 | In ballot, not final; do not build production interfaces on it | [Monitor] |
- Fix one release per interface and declare it in the server CapabilityStatement (
fhirVersion) and in the IG dependency list.
- Where partners use different releases, convert at a single gateway, never in each client; list each conversion and its data loss risk in section 3.3.
- Track the R6 ballot and the readiness of your IGs; plan a migration only when the national IGs and certified products move.
3.2 Implementation guides
| IG | Version | Base release | Why | Mandatory for |
|---|
| US Core (Example, US) | 9.0.0 (2026-05-31); check the version required by the ONC certification program and SVAP | R4 4.0.1 | Patient access and certified API baseline | UC-002, UC-003 |
| International Patient Summary (Example) | [Version] | R4 | Cross-border summary content | UC-003 |
| National core IG (Example, EU member state) | [Version] | [Release] | National profiles and terminology bindings | All |
| IHE ITI profiles | Section 6 | R4 | Document sharing, identity, directory | UC-001, UC-005 |
| SMART App Launch | 2.2.0 (2024-04-30) | R4 | App authorisation | UC-002 |
| Bulk Data Access | 3.0.0, STU 3 (2025-12-11); 4.0.0 in ballot | R4 | Population export | UC-004 |
| [IG] | [Version] | [Release] | [Why] | [Use cases] |
3.3 Version conversion register
| ID | From | To | Resources | Known loss or change | Mitigation | Owner |
|---|
| CNV-001 (Example) | R5 internal subscription events | R4 partner notifications | SubscriptionStatus, Encounter | R5 topic-based fields carried only through the R4 Subscriptions backport extensions | Partners use the backport IG; conversion tests per release | @platform-team |
| CNV-002 (Example) | R4 | R5 internal pilot | Observation, Patient | Renamed and moved elements handled by version conversion maps; extensions for elements absent in R4 | Use the HL7 cross-version extensions; reject on unmapped required elements | @interoperability-architect |
| [CNV-NNN] | [From] | [To] | [Resources] | [Loss] | [Mitigation] | [@owner] |
Never convert silently: record the source version in Provenance or a meta tag so that a downstream consumer can tell converted content from native content.
4. Resources and profiles
| Resource | Profile (canonical URL) | Interactions | Must-support decisions | Owner |
|---|
| Patient (Example) | [National core Patient] | read, search by identifier, name, birthdate | Identifier with system URI required; no free-text only names | @ehr-integration-lead |
| Encounter (Example) | [Core Encounter] | read, search by patient and date | Class and period required | @ehr-integration-lead |
| Observation (laboratory) (Example) | [Core laboratory result] | read, search by patient, category, code, date | LOINC code required, UCUM units | @lab-it |
| Condition (Example) | [Core Condition] | read, search | SNOMED CT or ICD-10 coding; clinical status required | @ehr-integration-lead |
| MedicationRequest (Example) | [Core MedicationRequest] | read, search | National medication terminology code | @pharmacy-it |
| DocumentReference (Example) | IHE MHD profiles | create through ITI-105 or ITI-65, search | Author, type, practice setting, confidentiality | @document-sharing-lead |
| Practitioner, Organization, Location, HealthcareService (Example) | IHE mCSD profiles | search | Active status, identifiers | @directory-lead |
| Provenance, AuditEvent (Example) | [Core Provenance], IHE BALP | create, search | Who, when, source system | @security-architect |
| [Resource] | [Profile] | [Interactions] | [Decisions] | [@owner] |
- Publish local profiles in a FHIR IG built with the HL7 IG Publisher, with examples and a version per release.
- Derive local profiles from the national core profiles; record each additional constraint and extension with a reason.
- Run the FHIR validator against every example and against sampled production payloads.
5. Terminology
| Domain | Code system | Edition or version | Binding strength | Source of truth |
|---|
| Problems and diagnoses (Example) | SNOMED CT; ICD-10 (national modification) for billing; ICD-11 where adopted | [National edition, release date] | Extensible | Terminology server |
| Laboratory tests (Example) | LOINC | [Version] | Required for results | Terminology server |
| Units (Example) | UCUM | Current | Required | Terminology server |
| Medications (Example) | [RxNorm / national medicinal product dictionary] | [Release] | Required | Terminology server |
| Document types (Example) | LOINC document ontology or national value set | [Version] | Required in MHD metadata | Registry configuration |
| Administrative codes (Example) | FHIR core code systems | Release in section 3 | Required | IG |
| [Domain] | [System] | [Version] | [Strength] | [Source] |
- Run a FHIR terminology server exposing
$expand, $validate-code, $lookup and $translate for every system in the table.
- Maintain maps (ConceptMap) for local codes, with clinical review of every map and a version per release.
- Load new code system releases on a schedule, test value set expansions and announce changes to partners.
6. IHE profiles and document sharing
6.1 Profiles and actors
| Profile | Version checked | Actor played by this solution | Transactions (IHE numbers) | Partners |
|---|
| MHD, Mobile access to Health Documents | 4.2.5 | Document Responder, Document Recipient | ITI-66 find lists, ITI-67 find document references, ITI-68 retrieve, ITI-65 or ITI-105 publish | Hospitals, GP systems |
| PIXm, Patient Identifier Cross-reference for Mobile | 3.1.0 | Patient Identifier Cross-reference Manager | ITI-83 query, ITI-104 feed | All participants |
| PDQm, Patient Demographics Query for Mobile | 3.2.0 | Patient Demographics Supplier | ITI-78 query (and ITI-119 match where supported) | All participants |
| IUA, Internet User Authorization | ITI TF Rev 20.2, Volume 1 | Authorization Server, Resource Server | ITI-71 get access token, ITI-72 incorporate token, ITI-102 introspect | All participants |
| mCSD, Mobile Care Services Discovery | 4.0.0 | Care Services Selective Supplier | ITI-90 find matching care services | Directory consumers |
| BALP, Basic Audit Log Patterns; ATNA (Example) | [Version] | Audit Record Repository | ITI-20 record audit event | Security operations |
| [Profile] | [Version] | [Actor] | [Transactions] | [Partners] |
Check every transaction number against the current profile page before publishing this design to partners.
6.2 Document query and retrieve sequence
The sequence shows UC-001: an emergency clinician's system resolves the patient's identifiers, finds documents and retrieves one, with a token checked at each step.
6.3 Patient identity matching
Patient matching is the main clinical safety risk in document sharing (HAZ-001). Design it explicitly:
| Item | Decision |
|---|
| Matching approach (Example) | Deterministic match on a national patient identifier where present; otherwise probabilistic matching on name, birth date, sex, address and phone with weighted scores |
| Thresholds (Example) | Score at or above [upper threshold]: automatic link; between [lower] and [upper]: manual review queue; below [lower]: no link |
| Review queue (Example) | Data stewards review queued pairs within [2 working days]; decisions are logged and feed threshold tuning |
| Unmerge (Example) | A wrong link can be undone; consumers are notified through the identity feed (ITI-104) and cached cross-references are invalidated |
| Query behaviour (Example) | PDQm returns candidates with a match grade; clinician systems show demographics for confirmation before displaying documents |
| Measures (Example) | False match rate and false non-match rate measured on the TST-005 set each release |
6.4 Relationship with XDS and cross-community exchange
| Item | Decision |
|---|
| Existing XDS.b infrastructure (Example) | Keep registry and repository; expose MHD as a facade (MHDS pattern or gateway) |
| Cross-community query (Example) | XCA gateways for national network; MHD for apps and smaller providers |
| Document formats (Example) | CDA documents kept as-is; new documents as FHIR Bundle (type document) where the national IG defines them |
| Metadata rules (Example) | Class, type, practice setting, facility type and confidentiality codes from the value sets in section 5 |
7. Authorisation and identity (SMART, IUA)
| Item | Decision |
|---|
| Patient-facing apps (Example) | SMART App Launch 2.2.0 standalone launch, PKCE required, the launch/patient scope for patient context, resource scopes in SMART v2 syntax (for example patient/Observation.rs) |
| Clinician apps in the EHR (Example) | SMART EHR launch with launch context and openid fhirUser |
| System to system (Example) | SMART Backend Services with asymmetric client authentication (private key JWT) and system/ scopes per partner |
| Cross-organisation document sharing (Example) | IUA tokens carrying subject, organisation and purpose of use |
| Identity proofing for patients (Example) | [National digital identity / portal proofing at NIST SP 800-63-4 IAL2 or national level] |
| Token lifetime and refresh (Example) | Access tokens [5 minutes] for system clients, [1 hour] for apps; refresh tokens only with offline_access and patient approval |
| App registration and vetting (Example) | Dynamic or manual registration with terms of use; information blocking rules considered before refusing an app (US) |
| Discovery (Example) | .well-known/smart-configuration published on each FHIR base URL |
Detail the identity provider design in CIAM Solution Design (security/ciam-solution-design) or IAM Solution Design (security/iam-solution-design).
8. Consent, privacy and regulatory touchpoints
8.1 Consent and access control
| Item | Decision |
|---|
| Consent model (Example) | Opt-out for direct care sharing within the region; explicit opt-in for research use |
| Representation (Example) | FHIR Consent resources in the consent registry; [IHE Privacy Consent on FHIR (PCF)] where adopted |
| Enforcement point (Example) | Access decision in the gateway combines token scopes, purpose of use, consent and confidentiality labels |
| Sensitive data (Example) | Security labels on resources (for example restricted categories under national law) filter results |
| Break the glass (Example) | Emergency access with reason, extra audit and review within [24 hours] |
| Patient access to logs (Example) | Patients can see who accessed their records through the portal |
8.2 Regulatory touchpoints
| Regime | Requirement (paraphrased) | Design response | Check |
|---|
| US HIPAA Privacy and Security Rules (45 CFR Parts 160 and 164) | Protect electronic protected health information with administrative, physical and technical safeguards; minimum necessary use | HIPAA Security Solution Design (compliance/hipaa-security-solution-design) | Current HHS rules and any final Security Rule update |
| US ONC/ASTP HTI rules | HTI-1 (Federal Register January 2024): certification updates, USCDI v3 baseline from 2026-01-01, decision support transparency, information blocking; HTI-2 (December 2024): TEFCA; HTI-4 (August 2025): electronic prescribing and prior authorisation; HTI-5 proposed deregulatory changes | Certified API conformance, US Core version per program requirements | healthit.gov HTI rules page for final status |
| US TEFCA | Nationwide exchange through Qualified Health Information Networks under the Common Agreement; FHIR-based exchange expanding | Connect through a QHIN or participant; map exchange purposes to section 8.1 | Current Common Agreement and SOPs |
| EU European Health Data Space, Regulation (EU) 2025/327 | In force 26 March 2025; applies generally from 26 March 2027 (Article 105); primary-use exchange of the first priority categories (patient summaries, ePrescriptions and eDispensations) from March 2029 and of the second group (medical images, laboratory results, hospital discharge reports) from March 2031; European EHR exchange format; requirements for EHR systems; secondary use through health data access bodies, largely from March 2029 | Map documents to the European exchange format; plan EHR system conformity | Consolidated text on EUR-Lex (Article 14 priority categories, Article 105 application) and implementing acts due by March 2027 |
| EU GDPR (Regulation (EU) 2016/679) | Health data is a special category (Article 9); DPIA for large-scale processing (Article 35) | DPIA (compliance/dpia) | Consolidated text and national law |
| [Regime] | [Requirement] | [Response] | [Check] |
9. Interface catalogue and integration architecture
9.1 Interface catalogue
| ID | Interface | Standard | FHIR release or v2 version | Direction | Security | Partners | Status |
|---|
| FX-001 (Example) | Patient access API | US Core or national core IG, SMART | R4 4.0.1 | Inbound reads | SMART App Launch | Any registered app | Live |
| FX-002 (Example) | Document query and retrieve | MHD, PIXm | R4 | Inbound | IUA | Regional hospitals | Pilot |
| FX-003 (Example) | Discharge summary publication | MHD ITI-65 | R4 | Outbound | Backend Services, mutual TLS | GP systems | Build |
| FX-004 (Example) | ADT feed from EHR | HL7 v2 ADT | v2.5.1 | Inbound to engine | VPN, mutual TLS | EHR | Live |
| FX-005 (Example) | Population export | Bulk Data Access | R4 | Outbound | Backend Services | Analytics platform | Build |
| FX-006 (Example) | Directory | mCSD | R4 | Inbound queries | IUA | All participants | Build |
| [FX-NNN] | [Interface] | [Standard] | [Version] | [Direction] | [Security] | [Partners] | [Status] |
9.2 Platform components
| Component | Responsibility | Product | Hosting | Owner |
|---|
| API gateway (Example) | Routing, rate limits, token validation, version conversion | [Product] | [Region] | @platform-team |
| Authorisation server (Example) | SMART and IUA tokens, client registry | [Product] | [Region] | @security-architect |
| FHIR server or facade (Example) | Serve profiles over EHR data | [Product] | [Region] | @ehr-integration-lead |
| Integration engine (Example) | HL7 v2 and CDA ingestion and transformation | [Product] | [Region] | @integration-team |
| Master patient index (Example) | Identity matching and cross-reference | [Product] | [Region] | @mpi-lead |
| Terminology server (Example) | Section 5 services | [Product] | [Region] | @terminology-lead |
| Audit repository (Example) | AuditEvent store, access reports | [Product] | [Region] | @security-architect |
- Store transformed copies only where a use case needs them, with a retention period; otherwise transform on read.
- Use FHIR Subscriptions (topic-based in R5, or the R4 backport IG) for event notification instead of polling where partners support it.
- Apply rate limits per client and protect EHR back ends with caching and query limits on expensive searches.
9.3 API behaviour rules
| ID | Rule |
|---|
| API-001 (Example) | Every error returns an OperationOutcome with a severity, a code and a human-readable diagnostic that contains no patient data |
| API-002 (Example) | Searches page results with a default _count of [50] and a maximum of [200]; clients follow the next link and never build page URLs themselves |
| API-003 (Example) | Updates use version-aware writes (ETag with If-Match) so that two writers cannot overwrite each other |
| API-004 (Example) | Creates from partner systems are conditional on a business identifier to stop duplicates on retry |
| API-005 (Example) | _include and _revinclude are limited to the combinations listed in the CapabilityStatement |
| API-006 (Example) | Every read and search writes an AuditEvent with the client, the user, the patient and the purpose of use |
| API-007 (Example) | Deprecated profile versions stay available for [12 months] after announcement, with a deprecation header |
| [API-NNN] | [Rule] |
10. Bulk data and analytics
| Item | Decision |
|---|
| Export level (Example) | Group-level $export for defined cohorts; no system-level export to external parties |
| Resource types (Example) | Patient, Encounter, Condition, Observation, MedicationRequest, Procedure |
| Incremental export (Example) | _since parameter for monthly deltas |
| Output and storage (Example) | NDJSON files in an encrypted bucket with short-lived signed URLs; deleted after [7 days] |
| Scheduling (Example) | Off-peak window [01:00 to 05:00] against a read replica |
| Privacy (Example) | De-identification or pseudonymisation before analytics where the purpose allows; purpose recorded |
| Downstream (Example) | Data Platform Architecture (architecture/data-platform-architecture) |
11. HL7 Version 2 and CDA coexistence
| Flow | Today | Target | Mapping | Owner |
|---|
| Admissions and transfers (Example) | HL7 v2 ADT A01, A02, A03, A08 | Keep v2 internally; publish FHIR Encounter and Patient | v2 to FHIR maps in the engine, versioned | @integration-team |
| Laboratory results (Example) | HL7 v2 ORU R01 | FHIR Observation and DiagnosticReport for external consumers | Map OBX to Observation with LOINC and UCUM | @lab-it |
| Orders (Example) | HL7 v2 ORM or OML | Unchanged | None | @integration-team |
| Discharge documents (Example) | CDA documents by post or v2 MDM | MHD publication of CDA, FHIR documents later | Metadata mapping only | @document-sharing-lead |
| [Flow] | [Today] | [Target] | [Mapping] | [@owner] |
Mapping governance: every map has a specification, test messages with expected FHIR output, clinical review for coded content and a version tied to the profile version.
12. Conformance testing and clinical safety
12.1 Tests
| ID | Test | Tool or method | Pass criterion | Evidence |
|---|
| TST-001 (Example) | Profile validation | FHIR validator with IG packages | Zero errors on examples and sampled payloads | Validation report |
| TST-002 (Example) | Core IG API tests | [ONC Inferno test kit / national test kit] | All required tests pass | Test kit report |
| TST-003 (Example) | IHE profile tests | IHE Gazelle tools, IHE Connectathon | Pass for each actor and transaction in section 6.1 | Connectathon results |
| TST-004 (Example) | SMART authorisation | SMART test suite or test kit | Scopes and launch contexts behave as specified | Test report |
| TST-005 (Example) | Patient matching | Curated test set with known duplicates and twins | False match rate under [target] | Matching report |
| TST-006 (Example) | Bulk export load | Export of [n] patients | Completes within FR-005 target | Load test |
| TST-007 (Example) | Security | Penetration test of gateway and authorisation server | No open high findings | Pentest report |
| TST-008 (Example) | Load and availability | Load test at 3 times VOL-003; availability monitoring | NFR-002 latency met; NFR-001 met over 30 days | Load test and monitoring reports |
| TST-009 (Example) | v2 and CDA mapping round trip | Test message sets per map in section 11 | Codes, units and values unchanged | Mapping test report |
| TST-010 (Example) | Discharge publication timing | End-to-end test from signing to GP retrieval | FR-004 target met in 99 % of runs | Scenario test record |
| TST-011 (Example) | Clinical safety case review | Hazard log walk-through with clinicians | Every HAZ control verified and residual risk accepted | Clinical safety case report |
| [TST-NNN] | [Test] | [Tool] | [Criterion] | [Evidence] |
12.2 Clinical safety
| Hazard ID | Hazard | Cause | Control | Verification |
|---|
| HAZ-001 (Example) | Wrong patient's documents shown | Identifier mismatch in cross-reference | Matching thresholds and review queue (section 6.3), demographic confirmation in UI | TST-005 |
| HAZ-002 (Example) | Result shown with wrong unit | Unit lost in v2 to FHIR mapping | UCUM required, mapping tests | TST-001, TST-009 |
| HAZ-003 (Example) | Missing documents assumed complete | Registry unavailable | UI shows which sources responded | TST-003 |
| [HAZ-NNN] | [Hazard] | [Cause] | [Control] | [Verification] |
12.3 Traceability
| Requirement | Design element | Test |
|---|
| FR-001 (Example) | FX-002, section 6 | TST-003 |
| FR-002 (Example) | PIXm, section 6.1 | TST-003, TST-005 |
| FR-003 (Example) | FX-001, section 7 | TST-002, TST-004 |
| FR-004 (Example) | FX-003 | TST-010 |
| FR-005 (Example) | FX-005, section 10 | TST-006 |
| NFR-001, NFR-002 (Example) | Section 9.2, VOL-003 | TST-008 |
| NFR-003 (Example) | Sections 7 and 8, API-006 | TST-004, TST-007 |
| NFR-004 (Example) | Section 11, CNV register | TST-001, TST-009 |
| NFR-005 (Example) | Section 12.2 | TST-011 |
| [ID] | [Element] | [Test] |
13. Operations, risks and decisions
13.1 Operations
| Activity | Approach | Owner |
|---|
| Partner onboarding (Example) | Registration, test kit evidence, agreement signed, production credentials | @interoperability-architect |
| Monitoring (Example) | Per-interface availability, latency, error rates, token failures | @platform-team |
| Clinical incident handling (Example) | Incidents with patient safety impact escalated to the clinical safety officer within [1 hour] | @clinical-safety-officer |
| Release management (Example) | IG and profile releases announced [60 days] ahead with a sandbox | @interoperability-architect |
| Audit review (Example) | Monthly access pattern review; patient access log requests answered within [n days] | @privacy-officer |
13.2 Risks
| ID | Risk | Likelihood | Impact | Response | Owner |
|---|
| RSK-001 (Example) | Partners on different FHIR releases | High | Medium | Single conversion gateway, R4 as exchange baseline, CNV register (section 3.3) | @interoperability-architect |
| RSK-002 (Example) | Patient matching errors | Medium | High | HAZ-001 controls, data quality programme | @mpi-lead |
| RSK-003 (Example) | Regulatory requirement versions change mid-programme | Medium | Medium | Quarterly regulatory review, section 8.2 | @compliance-lead |
| RSK-004 (Example) | Terminology licence gaps for partners | Low | Medium | Licence check during onboarding | @terminology-lead |
| [RSK-NNN] | [Risk] | [L / M / H] | [L / M / H] | [Response] | [@owner] |
13.3 Decisions
| ID | Decision | Alternatives | Date |
|---|
| DEC-001 (Example) | R4 4.0.1 as the exchange baseline | R5 for new interfaces | YYYY-MM-DD |
| DEC-002 (Example) | MHD facade on existing XDS infrastructure | Replace XDS | YYYY-MM-DD |
| DEC-003 (Example) | Keep HL7 v2 internally, FHIR externally | Convert all feeds | YYYY-MM-DD |
| [DEC-NNN] | [Decision] | [Alternatives] | YYYY-MM-DD |
Record each decision in full in an Architecture Decision Log (architecture/architecture-decision-log).
14. Glossary and references
14.1 Glossary
| Term | Meaning |
|---|
| FHIR | Fast Healthcare Interoperability Resources: HL7 standard for exchanging healthcare data as resources over REST and messaging |
| Implementation guide (IG) | Published set of profiles, extensions, terminology bindings and rules for a use case or jurisdiction |
| Profile | Constraint on a FHIR resource for a specific use |
| Must support | IG flag that a system must be able to handle an element as the IG defines |
| IHE actor | System role in an IHE profile, with the transactions it must support |
| SMART App Launch | HL7 IG for authorising apps to FHIR servers on OAuth 2.0 and OpenID Connect |
| NDJSON | Newline-delimited JSON, the output format of bulk export |
| QHIN | Qualified Health Information Network under TEFCA |
| MPI | Master patient index |
14.2 References
| Reference | Version or date | Use |
|---|
| HL7 FHIR R4, hl7.org/fhir/R4 | 4.0.1, 2019-10-30 | Exchange baseline |
| HL7 FHIR R5, hl7.org/fhir/R5 | 5.0.0, 2023-03-26 | Current release |
| HL7 FHIR R6 ballot, hl7.org/fhir/6.0.0-ballot5 | 2026-07-17, not final | Watch list |
| US Core IG, hl7.org/fhir/us/core | 9.0.0, 2026-05-31 | US core profiles |
| SMART App Launch IG, hl7.org/fhir/smart-app-launch | 2.2.0, 2024-04-30 | Authorisation |
| Bulk Data Access IG, hl7.org/fhir/uv/bulkdata | 3.0.0 STU 3, 2025-12-11 | Population export |
| IHE ITI Technical Framework, profiles.ihe.net/ITI/TF | Revision 20.2, 2025-11-11 | IUA and transactions |
| IHE MHD, PIXm, PDQm, mCSD, profiles.ihe.net/ITI | 4.2.5, 3.1.0, 3.2.0, 4.0.0 | Section 6 |
| ONC/ASTP HTI rules, healthit.gov/regulations/hti-rules | Page updated 2026-04-29 | Section 8.2 |
| Regulation (EU) 2025/327 (European Health Data Space) | OJ 2025-03-05, in force 2025-03-26 | Section 8.2 |
| SNOMED CT, LOINC, UCUM, ICD-10, ICD-11 | Editions per section 5 | Terminology |
Standard and licence note
Based on HL7 FHIR R4 (4.0.1) and R5 (5.0.0) and the HL7 implementation guides US Core 9.0.0, SMART App Launch 2.2.0 and Bulk Data Access 3.0.0 (HL7 FHIR content is published under the Creative Commons CC0 public domain dedication; HL7 and FHIR are registered trademarks of Health Level Seven International), the IHE ITI Technical Framework Revision 20.2 and IHE FHIR profiles (cited by name, version and transaction number), and public law and regulation (US HIPAA rules, ONC/ASTP HTI rules and TEFCA, Regulation (EU) 2025/327, Regulation (EU) 2016/679). Terminologies such as SNOMED CT and LOINC are named only and need their own licences. All text is original and no specification or legal text is reproduced. Check the current official versions, the R6 status and the consolidated legal texts before use. This is a documentation format, not legal advice. Template licence: MIT.