HL7 FHIR R5 was published March 2023. The specification delta from R4 is not cosmetic. Three categories of change create real engineering work for production systems: resource restructuring that breaks existing API contracts, the new Subscriptions framework that replaces R4's topic-based model with a fundamentally different channel architecture, and cross-version operations that introduce version negotiation complexity that most FHIR clients are not built to handle.
The Appointment and Encounter Restructuring
In FHIR R4, Appointment and Encounter are separate resources with a loose reference relationship. In R5, the Appointment resource gained significant new elements and the relationship to Encounter was restructured to support the full patient journey from scheduling through discharge. Specifically: the R5 Appointment resource introduces the subject element (replacing R4's participant-only model), basedOn references now support ServiceRequest directly, and the recurring appointment pattern uses a new RecurrenceTemplate backbone element that has no R4 equivalent.
For production EHR integrations, this means R4 Appointment-to-Encounter workflows that relied on the R4 participant cardinality rules will produce validation failures against an R5 server. More critically: payer and health information exchange partners migrating to R5 will expose R5 endpoints that your R4 client cannot consume without a translation layer. The CMS interoperability rules (CMS-9115-F) reference FHIR R4 but the ONC's USCDI v3 alignment is driving R5 adoption — the timeline pressure is real.
The cross-version operations specification (FHIR-VERSION header) allows a server to advertise R5 capability while accepting R4 requests via content negotiation. In practice, most FHIR server implementations (HAPI FHIR, Azure Health Data Services, Google Cloud Healthcare API) implement this incompletely. Test cross-version negotiation explicitly before relying on it in production.
The Subscriptions R5 Model
FHIR R4 Subscriptions use a channel-plus-criteria model: you define a channel (REST hook, email, websocket) and a criteria string (a FHIR search query). R5 replaces this with a topic-based model using SubscriptionTopic resources. The topic defines what events can be subscribed to. The Subscription resource then references a topic and specifies filter parameters and notification shape. This is a fundamentally different programming model — R4 subscribers query for data; R5 subscribers receive shaped notifications defined by topic authors.
The practical impact: if you have built R4-based subscription infrastructure for real-time clinical event notification (admit/discharge/transfer, lab result availability, medication dispensing), your R4 Subscription objects have no direct R5 equivalent. You must define SubscriptionTopic resources that model the same events, rebuild the subscriber registration flow, and handle the different notification payload format. HAPI FHIR R5 implements SubscriptionTopic as of version 6.4.0.
Migration Path for Live Production Systems
- Audit all R4 API consumers: classify each by which R4 resources they read/write and which R4 extensions they depend on — extensions that use R4 data types that changed in R5 are the highest-risk items
- Deploy an R4/R5 translation proxy (FHIR Converter or custom StructureMap transforms) between your R4 production system and any R5 partner endpoints — do not attempt direct R5 migration while R4 partners still exist
- Map R4 Subscription criteria to R5 SubscriptionTopic definitions before migrating — this requires topic authorship, not just client migration
- Test the Appointment and Encounter restructuring with real patient journey data from production — synthetic test data will miss cardinality edge cases that exist in your patient population
- Validate cross-version operations (FHIR-VERSION header handling) against each partner endpoint individually — do not assume server-advertised capability matches actual behaviour
- Plan for dual-write during transition: write R4 and R5 simultaneously to maintain backward compatibility with R4 consumers during migration
The ONC's Interoperability Standards Advisory (ISA) 2025 references R4B as the current recommended version for USCDI exchange, with R5 as "emerging." That guidance will shift — but the timeline means most organisations have 18-24 months to complete the R5 migration before it becomes a regulatory requirement rather than a technical preference.
The engineering behind this article is available as a service.
We have done this work — not advised on it, not reviewed documentation about it. If the problem in this article is your problem, the first call is with a senior engineer who has solved it.