Why Migrate to FHIR R5
FHIR R5, published as a normative standard by HL7 International in 2024, introduces substantial improvements over R4 that address real-world implementation gaps discovered during large-scale deployments. The ONC's 2025 Interoperability Standards Advisory recommends R5 adoption for new implementations and encourages migration planning for existing R4 systems.
The most compelling reason to migrate is the topic-based subscription framework. R4 subscriptions relied on criteria-based filtering that scaled poorly and provided limited control over notification delivery. R5 introduces SubscriptionTopic resources that define precise triggering events, combined with channel-agnostic notification delivery supporting REST hooks, WebSockets, email, and message queues. This enables event-driven architectures that were impractical with R4.
Clinical reasoning resources have been substantially expanded. PlanDefinition and ActivityDefinition now support complex branching logic for clinical decision support workflows. New workflow resources including refined Task and Transport resources standardize care coordination across organizational boundaries.
The European Health Data Space regulation explicitly references FHIR R5 capabilities in its technical specifications, making R5 compliance a prerequisite for participation in the EU health data infrastructure. Organizations that delay migration risk being excluded from this emerging ecosystem.
R5 also introduces improved provenance tracking, enhanced genomic data support through the MolecularSequence resource, and a mature evidence-based medicine resource set that supports structured clinical research data exchange.
Key Breaking Changes from R4 to R5
Understanding breaking changes is essential for planning a successful migration. While HL7 has maintained backward compatibility where possible, several changes require code modifications.
Subscription Model Replacement: The R4 Subscription resource is replaced by SubscriptionTopic and Subscription resources with a fundamentally different architecture. R4 subscriptions used criteria strings; R5 uses topic references with filter parameters. Migration requires rewriting subscription creation logic and notification handling.
Resource Renames and Splits: Several resources have been renamed or split. MedicationStatement has been replaced by MedicationUsage. DeviceUseStatement is now DeviceUsage. The CatalogEntry resource has been removed in favor of a more general approach. These changes require updating all references in code and data.
Search Parameter Changes: Some search parameters have been renamed, removed, or had their behavior modified. Organizations should run the HL7-provided comparison tool against their search parameter usage to identify impacted queries.
Extension Promotion: Several commonly used extensions in R4 have been promoted to first-class elements in R5. While this improves data modeling, it requires data transformation during migration. Examples include workflow status reason and recorded date elements.
Terminology Binding Changes: Some value set bindings have been strengthened from example to preferred or required, potentially requiring code system mapping updates. The R5 specification includes detailed change logs for each resource that should be reviewed systematically.
Migration Planning and Assessment
A structured migration plan reduces risk and ensures continuity of clinical operations.
Inventory Assessment: Catalog every FHIR resource type used in your implementation, including custom profiles, search parameters, operations, and extensions. Identify which resources are affected by R5 breaking changes and assess the scope of required modifications.
Dependency Mapping: Identify all systems that consume or produce FHIR data — EHRs, lab systems, pharmacy systems, patient portals, analytics platforms, and third-party integrations. Each dependency must be evaluated for R5 readiness and migration timing.
Profile Migration: If your organization uses custom FHIR profiles (StructureDefinitions), these must be updated to R5 base resources. The Firely SDK provides automated profile validation and migration tooling that identifies incompatibilities.
Test Environment: Establish a parallel R5 test environment alongside your production R4 system. Load representative data sets and validate all critical workflows before any production migration begins.
Migration Timeline: Plan for a dual-support period where your system accepts both R4 and R5 resources. This is essential when trading partners migrate on different timelines. The FHIR specification includes version negotiation capabilities through the fhirVersion parameter and Accept header versioning.
Rollback Strategy: Define clear rollback criteria and procedures. Data migration should be reversible, and the R4 system should remain operational until R5 has been validated in production for a defined stabilization period.
Technical Migration Steps
The technical migration follows a systematic process from dependency updates through validation.
Step 1 — Update FHIR Libraries: Upgrade your FHIR SDK to an R5-compatible version. Major implementations include HAPI FHIR 7.x for Java, Firely SDK 5.x for .NET, and fhir.js for JavaScript. Review the SDK release notes for API-level breaking changes.
Step 2 — Update Resource Definitions: Replace renamed resources, update changed element paths, and promote extensions to first-class elements where applicable. Automated transformation tools can handle many of these changes, but custom resources require manual review.
Step 3 — Migrate Subscriptions: Implement the new topic-based subscription model. Define SubscriptionTopic resources for each event type your system monitors. Update subscription creation to reference topics and implement the new notification bundle processing logic.
Step 4 — Update Search Queries: Review and update all search parameter references. Test each query against the R5 server to verify behavior matches expectations. Pay special attention to chained searches and include/revinclude patterns that may have changed.
Step 5 — Data Migration: Transform existing R4 data to R5 format. Use the FHIR conversion framework to automate bulk transformations. Validate converted resources against R5 profiles. Maintain referential integrity across all resource references during migration.
Step 6 — Integration Testing: Validate every external integration point with R5 data. Verify that trading partners can process R5 resources or that version negotiation correctly falls back to R4 where needed.
Dual-Version Support and Interoperability
In practice, healthcare ecosystems will operate with mixed R4 and R5 implementations for years. Your migration strategy must account for this reality.
Version Negotiation: FHIR's capability statement and content negotiation mechanisms allow servers to advertise supported versions and clients to request specific versions. Implement Accept header versioning to serve R4 or R5 representations of the same resource based on client capability.
FHIR Conversion API: The FHIR specification includes a $convert operation that transforms resources between versions. Deploying a conversion service at your API gateway allows you to accept R4 requests from legacy partners while storing and processing data in R5 internally.
SMART on FHIR Compatibility: SMART on FHIR applications should continue to function across versions, as the launch protocol and OAuth flows are version-independent. However, apps that depend on specific resource structures may require updates. Test all SMART apps against your R5 server before production deployment.
Bulk Data Export: The Bulk FHIR specification is version-aware. Ensure your bulk export implementation can produce both R4 and R5 NDJSON output based on client requests, as downstream analytics and research consumers may not upgrade simultaneously.
On-Kare's FHIR infrastructure supports simultaneous R4 and R5 operations, with automatic version negotiation and conversion, ensuring seamless interoperability throughout the healthcare ecosystem's migration timeline.
Post-Migration Optimization
Migration completion is the starting point for leveraging R5's advanced capabilities.
Event-Driven Architecture: With R5 subscriptions deployed, refactor batch-oriented workflows into event-driven patterns. Clinical events such as lab result filing, medication ordering, and discharge notifications can trigger real-time downstream processing rather than periodic polling.
Clinical Decision Support: Leverage R5's enhanced PlanDefinition and ActivityDefinition resources to encode clinical decision support logic as shareable, computable artifacts. This enables CDS rules to be distributed across systems and organizations through standard FHIR mechanisms.
EHDS Compliance: Map your R5 implementation to the European Health Data Space technical requirements. Implement International Patient Summary (IPS) profiles for cross-border patient data exchange. Prepare for secondary use data access requests through the EHDS Health Data Access Body framework.
Performance Optimization: R5's improved search capabilities and subscription efficiency often reveal performance optimization opportunities. Review query patterns, implement appropriate indexing, and leverage R5's enhanced caching mechanisms.
Monitoring and Observability: Implement comprehensive monitoring of R5-specific features including subscription delivery success rates, topic trigger frequency, and version negotiation patterns. These metrics provide early warning of integration issues and inform capacity planning.