If you work with both FHIR and openEHR, you have searched for this: a comprehensive, accurate mapping between FHIR R4 resources and openEHR archetypes. Every project that bridges these two standards needs it. And until now, the closest thing available was scattered across academic papers, GitHub repos, and community forum threads.
This is the reference. Every major FHIR R4 resource mapped to its openEHR archetype equivalent, with verified archetype IDs from the Clinical Knowledge Manager, mapping complexity ratings, and practical notes on where the mapping is clean and where it gets complicated.
Bookmark this page. You will come back to it.
Before the Matrix: Three Fundamental Differences
Before looking at individual mappings, you need to understand three architectural differences that affect every single mapping in the table below.
1. Standalone Resources vs. Nested Compositions
FHIR resources are standalone, independently addressable units. A Patient, an Observation, and a Condition each have their own ID and lifecycle. They reference each other via links. A Bundle or Composition merely groups references to these independent resources.
openEHR works differently. All clinical data lives inside Compositions. A Composition is committed atomically. The entries inside it (OBSERVATION, EVALUATION, INSTRUCTION, ACTION) do not exist independently. They are always part of a Composition, versioned as a whole.
Mapping consequence: Converting openEHR to FHIR requires "decomposing" a Composition into multiple standalone FHIR resources. Converting FHIR to openEHR requires "composing" standalone resources into a Composition with the correct template structure. This is bidirectional complexity that no mapping table can fully eliminate.
2. Generic Observations vs. Specific Archetypes
FHIR uses one Observation resource type for everything — vital signs, lab results, social history, assessments. Differentiation happens via the code field and FHIR profiles.
openEHR gives each clinical observation its own archetype with domain-specific data elements. Blood pressure has systolic, diastolic, mean_arterial_pressure, and pulse_pressure. Pulse has rate, regularity, rhythm, and character. Laboratory test result has test_name, specimen, and repeating analyte_result clusters.
Mapping consequence: A mapping engine must dispatch FHIR Observations to different openEHR archetypes based on the Observation.code. There is no single "Observation to Observation" mapping.
3. The 80% Rule vs. Maximal Data Sets
FHIR follows an "80% rule" — resources cover common use cases, and edge cases use Extensions. openEHR archetypes are designed as maximal data sets — every clinically relevant data point is included, even if rarely used. Templates then constrain archetypes to local needs.
Example: The FHIR vital-signs profile for blood pressure has systolic and diastolic components. If you need patient position, cuff size, or exertion level, you need extensions. In openEHR, blood_pressure.v2 includes all of these natively. The FHIRconnect paper found that mapping 24 international archetypes to 15 FHIR profiles required 34 FHIR extensions to capture the full archetype data.
The Entry Type Pattern
Before diving into individual resources, understand the pattern. openEHR organizes clinical data into four entry types. Each maps to a predictable set of FHIR resources:
| openEHR Entry Type | Purpose | FHIR Resources |
|---|---|---|
| OBSERVATION | Time-varying measured/recorded data | Observation, QuestionnaireResponse |
| EVALUATION | Persistent assessments and opinions | Condition, AllergyIntolerance, RiskAssessment, Goal, FamilyMemberHistory |
| INSTRUCTION | Orders and requests for future actions | MedicationRequest, ServiceRequest, NutritionOrder |
| ACTION | Records of performed activities | Procedure, MedicationAdministration, Immunization |
This pattern holds for nearly every mapping in the matrix below. If you know the openEHR entry type, you can predict which FHIR resource category it maps to.
The Complete Mapping Matrix
All archetype IDs below are verified against the openEHR CKM-mirror repository. CKM links are provided where numeric IDs are known.
Administrative and Demographic Resources
| FHIR R4 Resource | openEHR Archetype(s) | Complexity | Notes |
|---|---|---|---|
| Patient | CLUSTER.person.v1 + EHR object | Structural mismatch | openEHR separates demographics from clinical data. The EHR object holds the ehr_id linked to a subject. Patient demographics are either managed externally or via CLUSTER.person.v1 embedded in compositions. The DEMOGRAPHIC-PERSON archetype exists but has been unpublished since 2009. Most implementations store Patient demographics in FHIR and use openEHR only for clinical content. |
| Practitioner | CLUSTER.person.v1 | Structural mismatch | Practitioner info is typically carried as CLUSTER.person.v1 within composition composer or other_participations. DEMOGRAPHIC-ROLE.individual_provider.v0 exists but is unpublished. |
| Organization | CLUSTER.organisation.v1 | Structural mismatch | Used within clinical compositions. DEMOGRAPHIC-ORGANISATION.v0 exists but is unpublished. |
| Encounter | COMPOSITION.encounter.v1 + ADMIN_ENTRY.episode_institution.v0 | 1:many / partial | FHIR Encounter maps to the openEHR COMPOSITION context (timing, setting, facility) plus potentially ADMIN_ENTRY for admission/discharge details. The COMPOSITION is the container that holds clinical content. |
Vital Signs (9 Mappings)
| FHIR Observation Profile | openEHR Archetype | CKM | Complexity | Key Differences |
|---|---|---|---|---|
| Blood Pressure | OBSERVATION.blood_pressure.v2 | CKM | 1:1 | openEHR is richer — includes position, tilt, sleep status, exertion, 24hr average. FHIR uses component for systolic/diastolic; openEHR uses named data elements. |
| Body Weight | OBSERVATION.body_weight.v2 | CKM | 1:1 | openEHR includes state (dressed/undressed, confounding factors). |
| Body Height | OBSERVATION.height.v2 | CKM | 1:1 | Note: archetype name is height, not body_height. Includes position (standing/lying). |
| Body Temperature | OBSERVATION.body_temperature.v2 | CKM | 1:1 | openEHR includes body site of measurement and environmental conditions. |
| Heart Rate | OBSERVATION.pulse.v2 | CKM | 1:1 (partial) | No separate heart_rate archetype exists. Heart rate is recorded within the pulse archetype, which also covers regularity, rhythm, and character. |
| Oxygen Saturation (SpO2) | OBSERVATION.pulse_oximetry.v1 | CKM | 1:1 | openEHR is significantly richer — includes waveform, sensor site, ambient oxygen. |
| Respiratory Rate | OBSERVATION.respiration.v2 | CKM | 1:1 | openEHR includes rhythm, depth, pattern abnormality, inspiratory/expiratory ratio. |
| BMI | OBSERVATION.body_mass_index.v2 | CKM | 1:1 | Calculated value. openEHR includes clinical interpretation and confounders. |
| Head Circumference | OBSERVATION.head_circumference.v1 | CKM | 1:1 | Primarily used for neonatal/pediatric assessment. |
Laboratory and Diagnostics (3 Mappings)
| FHIR R4 Resource | openEHR Archetype(s) | CKM | Complexity | Notes |
|---|---|---|---|---|
| Observation (Lab) | OBSERVATION.laboratory_test_result.v1 + CLUSTER.specimen.v1 + analyte CLUSTERs | CKM | 1:many | Most complex mapping. FHIR uses a flat Observation per analyte. openEHR uses a panel model: one laboratory_test_result contains multiple analyte clusters. A FHIR DiagnosticReport + multiple Observations maps to one openEHR lab composition. |
| DiagnosticReport | COMPOSITION.report-result.v1 wrapping observation archetypes | — | 1:many | FHIR DiagnosticReport references standalone Observations. openEHR COMPOSITION.report-result.v1 directly contains the observation archetypes rather than referencing them. |
| ImagingStudy / Imaging Observation | OBSERVATION.imaging_exam_result.v1 | CKM | Partial | openEHR captures the clinical result/report. DICOM metadata and study-level info (FHIR ImagingStudy) has no direct openEHR equivalent. |
Clinical Findings and Assessments (5 Mappings)
| FHIR R4 Resource | openEHR Archetype(s) | CKM | Complexity | Notes |
|---|---|---|---|---|
| Condition | EVALUATION.problem_diagnosis.v1 | CKM | 1:1 (good) | Strong alignment. Both capture code, onset, severity, evidence. openEHR includes date_of_resolution and diagnostic_certainty. FHIR's clinicalStatus and verificationStatus map to openEHR's status and certainty fields. |
| AllergyIntolerance | EVALUATION.adverse_reaction_risk.v2 | CKM | 1:1 (good) | Good alignment. Both capture substance, manifestations, severity, criticality. openEHR archetype is richer with reaction events as repeating clusters. Note: version is v2 (not v1 as some older references state). |
| FamilyMemberHistory | EVALUATION.family_history.v2 | CKM | 1:1 (good) | Both model per-family-member conditions. openEHR includes a repeating per_family_member cluster with relationship, conditions, and age at onset. |
| Goal | EVALUATION.goal.v1 | — | 1:1 (partial) | Reasonable alignment. Both capture target, status, due date. openEHR goal is simpler than FHIR Goal. |
| ClinicalImpression | EVALUATION.clinical_synopsis.v1 + EVALUATION.recommendation.v2 + EVALUATION.problem_diagnosis.v1 | — | 1:many | No single openEHR archetype maps to ClinicalImpression. The FHIR resource combines assessment, findings, diagnosis, and plan. In openEHR, these are separate archetypes composed within a template. |
Medications (4 Mappings)
| FHIR R4 Resource | openEHR Archetype(s) | Complexity | Notes |
|---|---|---|---|
| MedicationRequest | INSTRUCTION.medication_order.v3 + CLUSTER.medication.v2 + CLUSTER.therapeutic_direction.v1 + CLUSTER.dosage.v2 | 1:many | Highly complex. A single FHIR MedicationRequest maps to an INSTRUCTION with nested CLUSTERs for medication details, dosage, and directions. The openEHR model is far more granular. Note: medication_order is at v3 (not v2 as older references state). |
| MedicationStatement | OBSERVATION.medication_statement.v0 | 1:1 (draft) | This archetype is at v0 (draft/unstable). It records a snapshot of medication use as reported by patient or clinician. |
| MedicationAdministration | ACTION.medication.v1 | 1:1 (partial) | The ACTION archetype tracks the full medication management lifecycle (planned, prepared, administered, suspended, completed). FHIR captures a single administration event. |
| Medication (substance) | CLUSTER.medication.v2 | 1:1 | Describes the medication substance, form, strength, and ingredients. Used within medication_order and other medication-related archetypes. |
Procedures, Orders, and Immunization (3 Mappings)
| FHIR R4 Resource | openEHR Archetype(s) | Complexity | Notes |
|---|---|---|---|
| Procedure | ACTION.procedure.v1 | 1:1 (good) | Good alignment. The FHIRconnect analysis found 19 openEHR elements aligning with FHIR Procedure fields, with 8 unmapped openEHR fields (procedure steps, scheduling details). |
| ServiceRequest | INSTRUCTION.service_request.v1 | 1:1 (good) | Both represent clinical orders/requests. The INSTRUCTION captures the order; the ACTION tracks fulfillment. FHIR ServiceRequest maps to INSTRUCTION; FHIR Task partially maps to ACTION. |
| Immunization | ACTION.medication.v1 within a vaccination template | Partial / structural | There is no dedicated immunization archetype in the international CKM. Immunization is modeled using ACTION.medication.v1 within a vaccination-specific template (COMPOSITION.vaccination_list.v0). Some national extensions create local immunization archetypes. |
Documents and Compositions (4 Mappings)
| FHIR R4 Resource | openEHR Archetype(s) | Complexity | Notes |
|---|---|---|---|
| Composition (FHIR) | COMPOSITION.* (various) | Conceptual mismatch | FHIR Composition is a document header that references contained resources. openEHR Composition is the fundamental unit of clinical content — all data lives inside it. FHIR Compositions reference; openEHR Compositions contain. |
| DocumentReference | CLUSTER.media_file.v1 | Partial | FHIR DocumentReference points to external documents. openEHR handles documents via CLUSTER.media_file.v1 for attachments, or by treating the entire Composition as the document. |
| CarePlan | COMPOSITION.care_plan.v0 + INSTRUCTION.care_plan_request.v0 + ACTION.care_plan.v0 | 1:many | All care plan archetypes are v0 (draft). openEHR uses COMPOSITION as container with embedded INSTRUCTION, ACTION, EVALUATION.goal.v1, and problem_diagnosis for addressed conditions. |
| Bundle | No direct equivalent | Conceptual mismatch | FHIR Bundle is a transport container. openEHR data is organized in Compositions within an EHR, committed as Contributions. |
Additional Clinical Resources (4 Mappings)
| FHIR R4 Resource | openEHR Archetype(s) | Complexity | Notes |
|---|---|---|---|
| Consent | ACTION.informed_consent.v0 | 1:1 (partial) | Both capture consent decisions. openEHR archetype is at v0 (draft). |
| RiskAssessment | EVALUATION.health_risk.v1 | 1:1 (partial) | Both assess future health risks. openEHR archetype captures risk factors with their presence/absence. |
| Specimen | CLUSTER.specimen.v1 | 1:1 | Good alignment. Used as a nested cluster within laboratory_test_result. |
| Device | CLUSTER.device.v1 | 1:1 (partial) | Captures device identification and type. openEHR device is simpler than FHIR Device (which includes UDI, safety characteristics). |
Data Type Mapping
Beyond resources and archetypes, the data types need mapping too. Here is the complete cross-reference:
| openEHR Data Type | FHIR Data Type | Notes |
|---|---|---|
DV_CODED_TEXT | CodeableConcept | Close mapping. Both allow multiple code mappings. openEHR's defining_code aligns with FHIR's userSelected coding. |
DV_TEXT | string or CodeableConcept.text | Parent of DV_CODED_TEXT. Allows free text where coding is optional. |
DV_QUANTITY | Quantity | Good mapping. Both carry value + unit + system. openEHR uses UCUM but also allows local units. |
DV_COUNT | integer or Quantity | Simple count; maps reasonably. |
DV_DATE_TIME | dateTime | Direct mapping. Both support partial dates. |
DV_BOOLEAN | boolean | Direct mapping. |
DV_IDENTIFIER | Identifier | Both carry value, system/issuer, type. |
DV_PROPORTION | Ratio | Both express ratios and fractions. |
DV_MULTIMEDIA | Attachment | Both carry binary content with media type. |
DV_DURATION | Duration | Both use ISO 8601. |
DV_INTERVAL<T> | Range or Period | Numeric ranges map to Range; datetime ranges map to Period. |
DV_URI | uri / Reference | openEHR URIs are plain references; FHIR References are typed and can be relative or absolute. |
DV_ORDINAL | CodeableConcept + integer | openEHR ordinals combine coded text with a numeric rank. |
DV_PARSABLE | string (with mime type) | For structured text like formulas. |
Existing Tools and Implementations
Several open-source projects have implemented portions of this mapping. If you are building a FHIR-openEHR bridge, start here rather than from scratch:
FHIRconnect (Better / Medical University of Vienna)
The most comprehensive mapping specification available. Published as a 2025 paper with an open-source YAML-based specification. Covers 24 international archetypes mapped to 15 FHIR profiles across 7 clinical domains, with 65% mapping reuse across projects. The CKM has recently added a FHIRconnect tab on published archetypes where these mappings can be browsed alongside the archetype definition.
openFHIR by Medblocks
An open-source runtime engine implementing the FHIRconnect specification. Tested against MII core dataset, US Core, and ABDM profiles. Provides a practical, deployable bridge between FHIR and openEHR systems.
EHRbase FHIR Bridge
An open-source Java project built on Apache Camel and the Open eHealth Integration Platform (IPF). Implements 30+ profile mappings, heavily focused on the German Corona Consensus Dataset (GECCO). Covers vital signs, conditions, procedures, lab results, immunizations, medication statements, and consent. Each FHIR profile/OPT pair has a dedicated converter class.
Code4Health Care Connect Adaptor
A UK NHS-focused adaptor that maps openEHR to FHIR CareConnect profiles. Includes detailed data type mapping documentation that remains a useful reference even for non-UK implementations.
What the Research Shows
Several academic papers have studied FHIR-openEHR mapping systematically. Key findings relevant to anyone building a bridge:
- One archetype can map to multiple FHIR resources. The oncology mapping study (2021) found that single archetypes often decompose into multiple FHIR resources, and single resource elements can map to multiple archetype elements.
- 34 FHIR extensions were needed to capture full archetype data when mapping 24 archetypes to 15 FHIR profiles (FHIRconnect, 2025). This quantifies the "openEHR is richer" claim.
- 65% mapping reuse across projects was achieved with a structured mapping specification (FHIRconnect). This means the initial investment in mapping pays off across subsequent implementations.
- Only 9.7% of published CKM archetypes have been formally mapped to FHIR profiles so far. The remaining 90% represent an open community effort.
- The GECCO dataset conversion (2022) demonstrated practical, production-grade openEHR-to-FHIR conversion as a deployable web service in the context of German COVID-19 data exchange.
The Five Mapping Gaps to Watch
Not every mapping is clean. These are the areas where the community has not yet settled on a standard approach:
- Demographics. All openEHR DEMOGRAPHIC model archetypes (PERSON, ORGANISATION, ROLE) have been unpublished at v0 since 2009. In practice, most implementations store demographics in FHIR and use openEHR only for clinical content. Whether the DEMOGRAPHIC model will ever be published, or whether CLUSTER.person.v1 is the de facto standard, remains unsettled.
- Immunization. There is no dedicated immunization archetype in the international CKM. National programs model immunization differently — some use ACTION.medication.v1, others use ACTION.procedure.v1, some create local archetypes. A FHIR Immunization resource has no single, standard openEHR target.
- Encounter classification. FHIR Encounter.class (inpatient, outpatient, emergency) maps loosely to openEHR COMPOSITION context settings, but the alignment is not clean. How to round-trip encounter metadata through openEHR is implementation-specific.
- FHIR References in openEHR. FHIR resources reference each other by ID (e.g.,
Patient/123). openEHR uses path-based addressing within compositions. How to preserve and round-trip FHIR reference semantics through openEHR storage is an open design question. - Care plans. All care plan-related archetypes are at v0 (draft). The FHIR CarePlan resource is rich and widely used. The mapping between them is workable but relies on unstable archetypes.
How to Use This Reference
If you are building a FHIR-openEHR bridge, here is the practical workflow:
- Start with the green rows. Vital signs and Condition/AllergyIntolerance have the cleanest 1:1 mappings. Get these working first to prove your pipeline.
- Use an existing engine. Do not build mapping logic from scratch. Start with openFHIR (if you want a runtime engine) or FHIRconnect spec (if you want a mapping language). Extend from there.
- Handle labs carefully. The laboratory test result mapping is the most complex in the entire matrix. FHIR's flat-per-analyte model vs. openEHR's panel-based model requires careful design. Plan for this.
- Decide on demographics early. Will you store Patient data in FHIR, openEHR, or both? This is an architectural decision that affects your entire integration.
- Check archetype versions. Archetype IDs include a version number. If you reference
adverse_reaction_risk.v1but the CKM has moved to v2, your templates and mappings may be outdated. Always verify against the CKM.
Contributing to the Mapping Effort
With only 9.7% of CKM archetypes formally mapped to FHIR, there is an enormous amount of community work still to do. If you are implementing FHIR-openEHR mappings in your project, consider contributing your mappings back:
- FHIRconnect specification — Submit mapping YAML files to the FHIRconnect-spec repository
- openEHR Discourse — Share your mapping experiences and edge cases on the openEHR community forum
- CKM — Published archetypes now have a FHIRconnect tab where mappings can be contributed
The more organizations that contribute their mappings, the less each new implementation has to reinvent. A comprehensive, community-maintained FHIR-openEHR mapping library is one of the highest-leverage investments the health informatics community can make.
Sources and Further Reading
- openEHR CKM-mirror — Authoritative archetype source
- FHIRconnect paper (2025) — Most comprehensive published mapping work
- Oncology mapping study (2021) — Manual mapping methodology for FHIR-openEHR
- GECCO conversion (2022) — Production openEHR-to-FHIR service
- openEHR Confluence data type cross-analysis
- EHRbase FHIR Bridge — Open-source mapping implementation
- openFHIR by Medblocks — FHIRconnect runtime engine
Share
Related Posts
ABDM Integration Milestones M1 to M4: The Complete Guide for Multi-Software Hospital Environments
India Has 834 Million Digital Health IDs. America Has TEFCA. Here's What the US Can Learn.
