R5 is the newest FHIR release, and most integrations still run R4. That gap is where teams have to keep both versions in mind, and where knowing what actually changed makes the R4-to-R5 conversation useful instead of theoretical. Most R4 resources carry over with modest updates. A handful changed enough to require thought before assuming the R4 mental model still fits. The site's R4 resource atlas sticks to R4 by design, but flags known R5 divergences. For the wider FHIR framing, additional EHR connectivity walkthroughs has more.
The Big Ones
Subscription — R5 replaces R4's push-only Subscription with the SubscriptionTopic + Subscription pair, a topic-based model that is closer to how event streams actually work. R4 integrations relying on the old REST-hook mechanic will not port cleanly.
MedicationRequest — R5 rearranges the dosage instruction and dispense request elements. Not a rename, but the structure is different enough that a client that reads R4 dosage without a translation layer will mis-parse R5 payloads.
Bundle — R5 tightens Bundle.type semantics and clarifies transaction handling on partial failure. R4 payloads survive, but the receiver's error-handling code path may need work.
CapabilityStatement — R5 adds several optional elements around bulk data and terminology capabilities. R4 clients read R5 statements without failing but do not see the new declarations.
The Rest Are Modest
Patient, Practitioner, Encounter, Observation, Condition, Procedure, DiagnosticReport, AllergyIntolerance, Organization — all carry over with modest edits. Element renames are rare; cardinality relaxations happen at the margins; value-set bindings shift on a few coded elements. A well-written R4 client tolerates most of these without changes.
For the ten resources most integrations touch, the ten FHIR resources you should learn first is the entry, and every one of them is safe to keep in an R4 mental model.
New Resources in R5
R5 adds a handful of resources that R4 does not have. Actor identity resources, more granular subscription topics, richer terminology resources. Whether they matter depends on the workload — most clinical integrations do not touch them yet, but reporting and research integrations often do.
What Not To Do
- Do not port an R4 client to R5 by version bumping the target and hoping the payloads still parse. Test each resource type explicitly.
- Do not assume the R5 CapabilityStatement is a superset of R4. It is close, but the coverage of specific features shifted.
- Do not build a client that pretends the two versions are one. Version negotiation is a first-class concern.
What To Do
- Read the R4-to-R5 migration notes per resource type at the HL7 site.
- Test the client against both versions in CI, not just one.
- Handle the version parameter in the CapabilityStatement and dispatch parsing per version.
- For resources with real structural differences (Subscription, MedicationRequest), keep the version-specific code paths clearly separated.
The R4 Bet Is Still Reasonable
R4 will keep serving the majority of production interoperability workloads for years. Committing to R5 for a greenfield project is defensible, but retrofitting an R4 integration to R5 is rarely the highest-leverage work. For the base pattern that survives both versions, navigating FHIR R4 resources when you know DomainResource but not much else is the entry.
The Short Version
Handful of resources changed enough to notice. Most carry over. Test per resource, dispatch per version, do not assume the mental model transfers whole. For reading resource definitions in either version, reading a FHIR resource definition the way developers read a class covers the pattern.
Sources
- HL7 canonical R5 versions chapter documenting major changes - HL7 canonical R5 versions chapter documenting major changes from R4
