HL7 FHIR R5 was published as a normative release in March 2023. CMS interoperability rules (CMS-0057-F, published January 2024) and ONC's HTI-1 final rule are creating timeline pressure for FHIR R5 adoption — APIs for Medicare Advantage plans, Medicaid, CHIP, and QHP issuers must be FHIR R4 compliant now, with R5 on the roadmap as CMS updates its API requirements.
The problem is not the regulatory timeline — it's the migration architecture. Most FHIR R4 implementations were built without designing for forward migration. The R4-to-R5 delta introduces breaking changes at the resource model level, the capability statement level, and the search parameter level. Organizations that haven't budgeted for the migration are going to find themselves facing a forced upgrade with an unbudgeted project.
The Breaking Changes That Matter
FHIR R5 restructures several core resources. The Encounter resource now includes a set of "reason" elements replacing the single reason field. The Medication and MedicationRequest resources were substantially revised. The Observation resource's component structure was changed. The CapabilityStatement resource gained new required elements. Any client or server implementation that relies on the specific structure of these resources — which is most of them — has breaking changes to resolve.
More impactful for most implementations: FHIR R5 changed how references work. The canonical URL approach for versioned resources was significantly revised. If your implementation uses FHIR canonical references for ValueSets, CodeSystems, or StructureDefinitions — which any implementation using custom profiles or terminology does — the R5 changes to canonical versioning require careful migration planning.
The FHIR R5 migration is not just a server-side problem. Every FHIR client — mobile apps, EHR integration layers, analytics pipelines, third-party apps connected via your patient access API — must be updated to handle R5 responses. If you operate a Patient Access API under CMS interoperability rules, your API clients include third-party apps over which you have no direct control. The migration strategy must include an R4/R5 parallel operation period long enough for registered apps to update.
The Migration Architecture
A viable R4-to-R5 migration for a production FHIR server serving multiple clients requires: (1) an R5 implementation running in parallel with the production R4 server; (2) a content negotiation layer that serves R4 or R5 responses based on the client's Accept-Fhir-Version header; (3) a data migration process that transforms R4 resources to R5 as they are written to the R5 server; (4) a sunset timeline for R4 support, communicated to API consumers with adequate notice.
The content negotiation layer is the architectural component most frequently omitted in migration planning. Without it, you must cut over all clients simultaneously — which is operationally impossible when your clients include third-party apps. The FHIR specification includes guidance for content negotiation via the Accept-Fhir-Version header, but implementing it requires a routing layer that can translate between R4 and R5 resource representations.
The Profile Migration Problem
US Core Implementation Guide profiles, the Da Vinci Implementation Guide profiles, and custom organizational profiles built on top of FHIR R4 must all be migrated to R5. The R5 versions of US Core (US Core 8.x) have breaking changes from R4-era US Core versions. Any conformance testing infrastructure — FHIR validators, Touchstone test scripts — must be updated to test against R5 profiles.
- Inventory every FHIR client connected to your server, including third-party apps registered via the SMART on FHIR directory
- Implement content negotiation support for Accept-Fhir-Version before any R5 migration work begins
- Run the FHIR R5 validator against your current R4 resource instances to identify which resources have breaking changes
- Plan for a 6-12 month parallel operation period for the transition — do not plan a hard cutover
- Update conformance testing to R5 profiles before migrating production data
- Communicate the migration timeline and deprecation schedule to third-party app developers at least 6 months in advance
Our healthcare technology practice has executed FHIR R4-to-R5 migrations for health system API programs. The common thread: parallel operation architecture and client communication are more complex than the server-side R5 implementation.
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.