How do you migrate from FHIR R4 to R5 without disrupting live clinical workflow?

Treat it as a boundary change against a canonical internal model, run both versions concurrently, and let the maturity labels tell you where the risk is.

Why this migration is different from an API upgrade

Teams tend to approach R4 to R5 the way they would approach any dependency bump, and HL7 says plainly that this instinct is wrong. Its Version Management Policy opens by noting that FHIR is a standard, so the way version change is handled is a bit different from an application API [1].

The difference is control. When you upgrade a library, you choose the date. When you change the version of a standard, you can only change your own side - the organizations you exchange data with will move when their own procurement, budget and clinical-safety cycles allow. There is no date on which everyone moves.

The version landscape reflects this. R5 is the current published release [2], R4 remains the baseline that a great deal of production traffic actually speaks [3], and R4B sits between them [4]. Any real deployment therefore has to speak to partners across more than one version at once.

The maturity model is a risk map

The most useful migration tool in FHIR is not a conversion script. It is the labelling the specification already carries.

HL7 uses five descriptive terms describing the level of stability and implementation readiness associated with different aspects of the specification [1]. Read as a migration risk map, they say roughly this:

Normative content is subject to defined rules for inter-version change once an artifact is Normative [1]. These are your stable dependencies - the parts of your integration least likely to require rework.

Trial Use content has been balloted but has less implementation experience behind it. Expect movement, and design so that movement is absorbable.

Draft content carries an unusually candid warning: HL7 describes it as content that should only be implemented by the brave or desperate and is very much "use at your own risk" [1]. Draft resources cannot have a maturity level greater than 2, and some draft-status resources sit at level 1 or 2 because the responsible committee is ready for testing and balloting but balloting has not yet occurred [1]. If a clinical workflow depends on Draft content, that is the first thing to review.

Informative content is provided for implementer assistance and does not make rules implementers are required to follow - tables of contents, registries, examples and implementer advice [1]. Useful, but not a contract.

Deprecated content is outdated and may be withdrawn in a future version. HL7's guidance is that implementers who already support it should continue to do so for backward compatibility, should avoid adding new uses, and should follow the specification's guidance on what to use instead [1].

The trap inside Normative

There is one detail here that catches careful teams, and it is worth reading twice.

Some Normative artifacts contain a few parts labelled Trial Use even though the artifact itself is labelled Normative: some normative resources contain elements labelled trial-use, and some normative pages contain trial-use sections [1]. HL7 says it prefers to avoid this outcome, but that there are resources whose overall functionality is clearly ready to be labelled normative while some very specific parts lack the requisite implementation experience - and it gives Bundle.signature as an example [1]. Where a Normative resource contains elements marked trial-use, those elements are clearly marked in the resource definitions, and implementers should be aware that future versions may change them [1].

The practical implication is that migration risk assessment has to be done at element granularity, not resource granularity. "We only depend on Normative resources" is not a sufficient statement. The question is which fields of those resources you depend on.

The architecture that makes this survivable

Everything above is manageable if one architectural decision was made correctly, and painful if it was not.

The internal model must not be a FHIR version. When application code treats FHIR resources as its domain objects, a version change propagates through persistence, business logic and interface. In clinical software that means revalidating workflows that are carrying real patients - which is both the expensive outcome and the risky one.

With a canonical internal model, each version is an adapter. Migration becomes: write the R5 adapter, run it beside the R4 adapter, verify equivalence, and move partners across individually. The core never stops working, and no clinical workflow is revalidated because the workflow never changed.

Version negotiation belongs in configuration, not in code. With R4, R4B and R5 all live [2][3][4], the version a given exchange uses is a property of the partner relationship. Hardcoding it guarantees a code change every time a partner moves.

Mappings deserve tests. HL7 publishes extensions for converting between versions as part of its version management approach [1], but a conversion that is structurally valid can still be clinically wrong. Each mapping is a place where meaning can shift quietly, and quiet shifts in clinical data are the failures that do not announce themselves.

How to verify equivalence before you trust it

Running two adapters side by side is only useful if you can tell whether they agree. The technique that works is shadow comparison: for a defined period, serialise the same canonical record through both the R4 and R5 adapters, compare the results field by field, and record every divergence rather than every failure. Most divergences will be expected and benign - a renamed element, a restructured backbone. The ones worth stopping for are the divergences nobody predicted, because those indicate a mapping assumption that was never written down.

Two rules make that exercise honest. Compare against real traffic shapes rather than curated examples, because curated examples encode the same assumptions as the mapping. And treat an absent field as a divergence, not as a match - silently dropping an element is the single most common conversion defect and the hardest to notice, since the output remains structurally valid and simply says less than it should.

Only once the divergence log has gone quiet across representative traffic is it reasonable to move a partner. That is a slower path than a cutover, and it is the reason it does not produce an outage.

Concurrent operation is the precedent, not the compromise

Running two versions side by side sometimes gets framed as technical debt or a failure to commit. The standards body's own history says otherwise.

HL7 committed to supporting and extending Version 2 in parallel with Version 3, explicitly to provide continuity for current installations [5]. That is the same organization that publishes FHIR, choosing parallel operation over forced migration for the exact reason that applies here: the installed base carries real clinical traffic and cannot be moved by fiat.

So the honest migration plan for a live system is not a date. It is an adapter, a test suite over the mappings, per-partner configuration, and an element-level review of every dependency against its maturity label. MapleTriage is being built in Moncton, New Brunswick on that pattern rather than against a single pinned version. It is in development and not generally available.

By Joel Gathercole · Published 2026-08-23