# Migration to FHIR R6: Principles and Strategy for US Core

## Introduction

The Fast Healthcare Interoperability Resources (FHIR) standard, developed by HL7, continues to advance healthcare interoperability in the United States. US Core, an implementation guide (IG) built on FHIR, establishes the foundation for exchanging health data aligned with the United States Core Data for Interoperability (USCDI). With FHIR R6 on the horizon, the Argonaut Project met to develop a plan to facilitate transition from the current FHIR R4-based US Core to FHIR R6. This whitepaper presents a set of guiding principles and a draft strategy for transitioning US Core to FHIR R6.

### Background on FHIR and US Core
FHIR enables secure, efficient health data exchange globally. FHIR US Core has achieved significant success as a cornerstone of healthcare interoperability in the United States, driven by its alignment with the United States Core Data for Interoperability (USCDI) and its adoption across diverse stakeholders. Currently based on FHIR R4, US Core is updated annually to support the latest requirements from ASTP U.S. Core Data for Interoperability (USCDI). FHIR R6 introduces normative maturity, structural improvements (e.g., CodeableReference datatype), and other significant enhancements, making migration essential for future-proofing interoperability.

### Need for Migration
Transitioning to R6 will align US Core with the latest FHIR capabilities with the goals of improving data quality and addressing evolving implementation needs. It signals to government and industry a commitment to progress while carefully managing disruptions and breaking changes.

### Goals of This Whitepaper

- Define principles to guide the migration.

## Guiding Principles

Developed through Argonaut discussions and surveys, these principles ensure a predictable, minimally disruptive migration for US Core's read and search APIs:

1. **Single-Version Development for New USCDI Releases**: US Core will only develop based on new USCDI releases on either FHIR R4 or FHIR R6 not both. This estabishes a clear path for both regulators and implementers and reduces development costs.

2. **Focus on Compatibility from R4 to R6**: US Core will document recommendations and guidance to support the transitions directly from FHIR R4 to FHIR R6. US Core will not document transitions to and from FHIR R5. This reflects FHIR R4’s dominance in the US ecosystem and the need to provide clear implementer guidance.

3. **Clear Documentation of Breaking Changes**: US Core will summarize FHIR R4-R6 breaking changes on a dedicated page, defining the major changes patterns (e.g., cardinality, datatype changes) and the potential impact for the various US Core actors (e.g., Facade vs Native FHIR Servers, Clients) to guide planning.

4. **Extended Support for FHIR R4**: We recognize that FHIR R4 support will continue for years post-R6 release, and there will be a variety of FHIR R6 adoption timelines. Once a systems is live on R6 they may choose to freeze further enhancments on R4.

5. **Preservation of Prior Design Decisions**: US Core strives to maintain consistency with its interpretation of USCDI and foundational designs when transitioning to FHIR R6. Changes to prior design decisions will be limited to cases where FHIR R6 enhancements necessitate redesign or where specific exceptions* are deemed necessary.

\*Survey feedback identified these potential exceptions which will be resolved before the R4-R6 transition

- Clinical Notes: Explore consolidating notes in DocumentReference.
- Medications: Introduce MedicationAdministration and MedicationStatement and update to medicaion list guidance.

<!-- ## Argonaut Next Steps

Test early R6 designs to determine if a larger Argonaut R4->R6 transition project is necessary in 2026.

### Timeline
- **Q3-Q4 2025**: Complete prototypes; host virtual connectathon (October 27th week or November) on <10 R6 profiles (e.g., Patient, AllergyIntolerance, Encounter, DocumentReference, Device, Procedure, Lab Observation) to test change patterns.
- **2026**: Conduct design meetings (January), connectathons (May, September), and complete port. Ballot R6-based US Core post-normative R6.
- **2027+**: Publish USCDI-aligned versions (e.g., v10 in May 2027); enforce after 4-6 years.

### Prototyping
Build an R6 branch of US Core v8. (vs V6 ??), focusing on structural R4-to-R6 transformations. Prioritize and limited set of ~10 resource types, categorized by medium-high level of effort (LOE). (See Appendix A for a table summarizing the LOE by type). Prototypes to include updated profiles, R4-R6 mapped examples, and issues tables.

### Testing
Host Connectathons to get early feedback for FHIR R6 Ballot comments
- limited number of profiles.

### Communication and Feedback
To further enhance stability and foste a smoother migrations, we will encourage HL7 workgroups to minimize breaking changes in FHIR R6 both informaly and formally through the HL7 Ballot process.

### Best Practices for Implementation
- **Production Systems**: Implement distinct R4 and R6 endpoints to support parallel operations. Document facade patterns for compatibility.
- **R4 Sunset Period**: Plan for 4-6 years post-R6 release, aligned with enforcement (e.g., USCDI v7-based US Core v10 in May 2027 if R6 publishes by Sept 2026).

### Tools
- **R4-R6 mapping templates**: FHIRPath-based transformation tools
- **Postman collections** for testing
- **Validators** for quality assurance.
-->
## Conclusion
The migration to FHIR R6 is the next step in maintaining US Core’s role in healthcare interoperability. This whitepaper, informed by the Argonaut Project’s collaborative efforts, lays the foundation for a successful transition. By adhering to the proposed principles and strategy, US Core goal is to smoothly, predictably transition from R4 to R6.

<!-- ## Appendix A: FHIR R4-FHIR R6 LOE by Profile Type

| Category | Description | Examples of US Core Profiles |
|----------------|-------------|------------------------------|
| No Change | Fully compatible; no updates needed. | Patient, Immunization, Medication, Practitioner, RelatedPerson. |
| Low-Medium LOE | Minimal changes; simple mappings. | AllergyIntolerance, CarePlan, CareTeam, Condition (Encounter Diagnosis and Problems/Health Concerns), DiagnosticReport (Lab and Note), Goal, Location, MedicationDispense, Organization, PractitionerRole, QuestionnaireResponse, ServiceRequest, Specimen, Various Observations (e.g., ADI Documentation, Clinical Result, Lab Result). |
| Medium-High LOE | Significant changes; complex mappings and breaking issues. | Coverage, Implantable Device, DocumentReference (including ADI), Encounter, MedicationRequest, Procedure. | -->