FHIR R4 vs R4B vs R5: What Changed and Which Version to Use

FHIR has gone through several major releases: DSTU2, STU3, R4, R4B and R5, with R6 under development. Each release is a complete specification, and resources from different releases are not wire-compatible by default, so a client and server must agree on one. A server advertises its version in the fhirVersion element of its CapabilityStatement.

Normative content in R4 carries HL7's backward-compatibility commitment, which is one reason R4 has proven durable. Trial-use resources do not carry that commitment, so most of the differences between R4 and R5 are concentrated there.

R4B was published to give certain communities, notably regulatory medication definition and evidence-based medicine work, stable versions of resources they needed before R5 was ready. It reworked resources in those areas and added the SubscriptionTopic and SubscriptionStatus resources to support the subscriptions backport. For typical clinical integration, R4B behaves very much like R4 and offers little reason to move; treat it as a special-purpose release unless an implementation guide you depend on requires it.

R5 is a large release. The changes below are the ones most likely to affect architects and developers; the full list is in the version history and difference pages of the R5 specification.

Version choice is driven less by features than by who you need to exchange data with. In the United States, the ONC certification criteria for standardized API access reference US Core and SMART App Launch, and the US Core versions named there are built on R4. CMS interoperability rules for payer APIs likewise point to R4-based implementation guides. Major EHR platforms expose R4 APIs to meet those requirements. A new system that speaks only R5 would struggle to connect to the EHRs and payers it actually needs.

Outside the US the picture is similar: many national and international implementation guides, including the International Patient Summary, have been published on R4. That ecosystem of profiles, test tools, libraries and trained developers is a strong reason to stay put until the guides you depend on move.

Moving between FHIR versions is a data and contract migration, not a library upgrade. Plan it as you would any FHIR migration project:

1. Inventory the resources, profiles, extensions, search parameters and operations you use today.
2. Map each element across versions. HL7 publishes cross-version extensions and conversion maps that help, but every mapping needs human review, particularly for restructured resources.
3. Decide whether to run dual endpoints during the transition. Many organisations expose R4 to external partners while using newer features internally.
4. Re-validate stored data against the new profiles; data that was valid in R4 can fail R5 validation.
5. Update clients, test suites and documentation, and give partners a clear deprecation timeline.

For greenfield internal systems with no regulatory exposure, starting on R5 can be reasonable, especially if topic-based subscriptions are central. Even then, check that your chosen server and client libraries support R5 fully; the FHIR server architecture guide covers what to evaluate.

The base version also determines which tools you can rely on. Validators, client libraries, code generators, test kits and implementation guide publishing all target specific releases. Mature open-source servers such as HAPI FHIR support several versions, but each server instance or endpoint typically serves one version, and features introduced in R5 may arrive in libraries before they are hardened in production servers.

• Confirm that your server, client SDKs and validator all support the exact version and package of each implementation guide you plan to use.
• Use the FHIR version parameter on the application/fhir+json media type when an endpoint might serve more than one version, so clients and servers can negotiate explicitly.
• Conformance test kits, including ONC's Inferno tests for US certification criteria, are built around R4-based guides; plan your test strategy around what your partners will test you with.
• Keep version-specific code paths isolated. A thin mapping layer between an internal model and the external FHIR version makes later upgrades far cheaper.

If the version decision is tangled up with vendor selection, an independent FHIR consulting review of your partners' requirements is usually cheaper than discovering a mismatch during integration testing.