FHIR R5 vs R4: What Actually Changed, and Should You Upgrade in 2026?
An accurate look at FHIR R5 for teams on R4: the release timeline, R4B, the element changes that break code, new and renamed resources, and how to decide.
By the FHIR Toolbox team, Omindra Labs · 5 min read ·
Checked against the official specifications listed under Standards and references at the end of this article.
Most FHIR in production today is R4. R5 has been published since 2023, every new specification discussion seems to assume it, and teams keep asking whether they're falling behind. The honest answer depends on who you exchange data with. This article explains what changed between R4 and R5, which changes break existing code, and how to decide.
The release timeline
| Release | Version | Published | Status today |
|---|---|---|---|
| R4 | 4.0.1 | October 2019 (4.0.0 was December 2018) | The production baseline almost everywhere |
| R4B | 4.3.0 | May 2022 | A narrow update to R4, mainly the medication-definition and evidence resources |
| R5 | 5.0.0 | March 2023 | Current published release |
| R6 | — | In development | Check the HL7 FHIR version history for status |
R4B exists because some communities, especially regulatory medication data, needed changes to a few resources without waiting for R5. For Patient, Observation, Encounter and the other everyday clinical resources, R4B is effectively the same as R4.
What "normative" means — and doesn't
R4 was the first FHIR release with normative content, meaning HL7 commits to backward compatibility for it. The normative parts include the base data types, the RESTful API, JSON and XML formats, and a small set of resources such as Patient, Observation, Bundle, StructureDefinition, CodeSystem and ValueSet.
Most resources, including Encounter, Condition, MedicationRequest and Procedure, are still trial use in both R4 and R5. Each carries a maturity level (FMM 0–5) on its specification page, and trial-use resources can change between releases. That's why R5 could rework Encounter but couldn't make breaking changes to Patient.
So R5 isn't "R4 made stable". It's R4's stable core plus another round of changes to everything else.
Changes that break R4 code
Encounter
The most-changed common resource. Code written for R4 Encounters won't read R5 Encounters correctly:
| R4 | R5 |
|---|---|
status: planned | arrived | triaged | in-progress | onleave | finished | cancelled | ... | status: planned | in-progress | on-hold | discharged | completed | cancelled | discontinued | entered-in-error | unknown |
class — a single Coding | class — an array of CodeableConcept |
period | actualPeriod, plus new plannedStartDate / plannedEndDate |
hospitalization | admission |
reasonCode + reasonReference | reason (each with use and value as CodeableReference) |
diagnosis.condition (Reference) | diagnosis.condition (CodeableReference), with use as a CodeableConcept array |
CodeableReference replaces many choice types
R5 introduced the CodeableReference data type: a concept, a reference, or both. It replaces many R4 pairs of "code or reference" elements:
// R4 MedicationRequest
"medicationCodeableConcept": {
"coding": [{ "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "197361", "display": "Amlodipine 5 MG Oral Tablet" }]
}
// R5 MedicationRequest
"medication": {
"concept": {
"coding": [{ "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "197361", "display": "Amlodipine 5 MG Oral Tablet" }]
}
}
The same pattern appears in reason elements across many resources (reasonCode/reasonReference become reason).
Subscriptions
R4 subscriptions were criteria-based: "notify me when a search for Observation?code=... would return something new". R5 replaces this with topic-based subscriptions:
- SubscriptionTopic — the server defines named events (for example "encounter started").
- Subscription — a client subscribes to a topic with filters and a channel (REST hook, websocket, email, message).
- SubscriptionStatus — sent with each notification in a
subscription-notificationBundle (a new Bundle type), with event counts so clients can detect missed events.
Because this design was useful too soon to wait for R5 adoption, HL7 publishes the Subscriptions R5 Backport implementation guide, which brings topic-based subscriptions to R4 servers. Many R4 systems that support "R5 subscriptions" do it through the backport.
Renamed and removed resources
- RequestGroup became RequestOrchestration.
- DeviceUseStatement became DeviceUsage.
- Media was removed. Images, video and audio now go in DocumentReference.
- CatalogEntry was removed.
New resources worth knowing
R5 adds resources for areas FHIR didn't model well before, including SubscriptionTopic and SubscriptionStatus, Transport (movement of things and people), InventoryItem and InventoryReport, GenomicStudy, ImagingSelection, ArtifactAssessment, Permission, ActorDefinition and Requirements. Many are at low maturity levels. Check the FMM level before you build on one.
Changes that don't break code
Plenty of R5 changes are additive: new optional elements (for example Observation.triggeredBy), new search parameters, new codes in extensible value sets, and clarified definitions. An R4 reader mostly ignores these. An R4 *validator*, however, will flag new elements as unknown, which is how version mixing usually shows up.
Version mixing: the real-world problem
The most common R5-related bug isn't a missing feature. It's an R4 system receiving an R5-shaped resource, or the other way round, with no error until something downstream breaks. Protect against it:
- Read
fhirVersionfrom the server's CapabilityStatement (GET [base]/metadata):4.0.1,4.3.0or5.0.0. - Use the
fhirVersionMIME parameter where servers support it:Accept: application/fhir+json; fhirVersion=4.0. - Validate against the exact version you target. Never mix R4 and R5 elements in one resource.
- Keep version-specific code paths separate. Don't add "if R5 then …" branches throughout a mapper.
Should you upgrade?
Stay on R4 if you exchange data with US EHRs, payers or public health. US Core, the ONC certification criteria and payer APIs are built on R4, and the EHRs you connect to serve R4. Being on R5 would add a translation layer, not remove one.
Consider R5 if you're building a new system with no R4 partners, you need features that exist only in R5 (such as the new inventory, transport or genomics resources), and your server platform supports it fully. HAPI FHIR and several commercial servers do, but check the specific resources you need.
Prepare either way. Write mapping code with the version as an explicit parameter, keep R4 and R5 models separate, and use the topic-based subscriptions backport if you need event notifications on R4. When your partners move, possibly to R6 rather than R5, the migration will be a contained change.
Try it
Compare any resource across versions in the R4 vs R5 comparison, which lists added, removed and changed elements generated from the official specification files. Browse definitions in the R4 reference and R5 reference, and switch the FHIRPath playground between R4, R4B and R5 to see how the same expression behaves against each version's model.
Standards and references
- FHIR version history (official directory)
- FHIR R5 specification
- FHIR R5: Encounter
- FHIR R5: Subscriptions framework
- Subscriptions R5 Backport IG
- US Core Implementation Guide
FHIR Toolbox is a free collection of HL7 FHIR tools by Omindra Labs. The tools process your data in your browser; it is not uploaded for normal tool operations.