Hello OpenEMR FHIR Developers and Consumers,
We’re planning some significant changes to the OpenEMR FHIR API in the coming months and would love your input. These updates are primarily driven by regulatory requirements and growing international use, and we want to make sure the direction we take works for the broader OpenEMR community.
Background & Motivation
In the U.S., we need to comply with the ONC’s 20 25 year-end FHIR certification requirements, which means aligning with US Core 6.1.0, ideally targeting US Core 7.0.0.
We’re also collaborating with groups in Europe and Canada to evaluate rolling out the International Patient Summary (IPS) Implementation Guide (IG).
All changes are based on the FHIR R4/R4B base specification.
What’s Changing
These updates will require:
- New FHIR resource endpoints
- Modifications to existing data elements
- Support for multiple, potentially conflicting, IGs (e.g., US Core vs IPS)
Feedback Needed: API Versioning & Profile Selection
We’re considering several strategies for versioning and profile management. Your feedback here is especially important.
Option 1: URL Versioning
- Use versioned paths like
/v1/
,/v2/
, etc. /v2/
would support the latest compliant standard (e.g., US Core 6.1.0)
Option 2: IG-Specific Paths
- Label endpoints by IG:
/us-core-3-1-1/
,/us-core-6-1-0/
,/ips-1-1-0/
Option 3: FHIR Base Version Paths
- Label by FHIR base version:
/R4/
,/R4B/
- Use
meta.profile
to determine applicable IG/profile
Option 4: Accept Header Negotiation
- Client specifies desired IG via the
Accept
header - Fallbacks:
meta.profile
, then a server-wide default setting
Preferred? Some major platforms (HAPI, Google, Azure) validate resources against a list of supported profiles for each base version. This could work for us—assuming profile conflicts can be resolved or managed.
FHIR Write Capabilities (Stretch Goal)
We aim to enable FHIR write support, potentially requiring:
- An external reconciliation layer before data is ingested
- Configuration to allow/disallow client writes without clinician review
Your thoughts?
- Should clients be allowed to push data directly?
- Which resources (if any) are safe to allow this for?
- Should write support be configurable?
Profile Translation Layer
Today, OpenEMR maps:
FHIR Resource → OpenEMR Resource → DB Record
We’re exploring adding a translation layer to manage different IGs:
FHIR Profile Mapper → FHIR Resource → OpenEMR Resource → DB Record
Examples:
USCorePatientMapper
IPSPatientMapper
ClinicalQualityMetricPatientMapper
Thoughts on this structure? Anyone implementing something similar?
Identified Resource Changes & Data Elements
To meet USCDI V3 and V4, we anticipate changes to ~35-50 data elements. This includes support for:
ServiceRequest
– SDOH, reason for referralQuestionnaire
/QuestionnaireResponse
– Health assessmentsCondition
,Coverage
,CareTeam
,Encounter
,Goal
Specimen
,RelatedPerson
,Patient
(new demographic fields)MedicationRequest
&MedicationDispense
Observation
– including vital signs, smoking status, pregnancy, etc.DocumentReference
– clinical notes, screening assessments
SMART on FHIR Updates
We’re planning to update our authorization/authentication to support:
- SMART on FHIR v2.2
- Launch context with encounter populated
- New
context/resource.CRUDS
scope syntax - Fine-grained scope binding:
context/resource.CRUDS?search-id=xyz
Server Architecture: PHP FHIR Server vs. HAPI FHIR
As we make these substantial updates, we’re also revisiting the underlying server implementation. Currently, OpenEMR uses a custom PHP-based FHIR server, which aligns with the rest of the codebase and avoids introducing new language or dependency barriers.
However, there’s growing interest in HAPI FHIR, which offers:
- Robust IG support
- Continuous maintenance and upgrades
- A broader community of contributors
Tradeoff: HAPI strongly discourages MySQL due to known performance limitations, and switching would add complexity around deployment and integration.
We’ve noticed several OpenEMR forks or installations integrating HAPI on their own. Before we commit, we’d like to understand:
- Are you or your organization currently using HAPI FHIR with OpenEMR?
- Do you prefer maintaining a lightweight, PHP-native server?
- Would moving to a Java-based HAPI server be a blocker or benefit in your environment?
This decision has long-term implications for community contribution and maintainability, so your input is especially valuable.
What We Need From You
We’d love to hear your feedback on:
- Preferred versioning/profile strategy
- FHIR write capability configuration
- Translation layer design
- Server architecture: PHP vs. HAPI
- Anything else you think we’ve missed
Your input will help shape OpenEMR’s FHIR direction in a way that works for implementers, integrators, and end users alike.
Thanks,
Stephen Nielson
OpenEMR Project Administrator
OpenEMR Foundation Director of Engineering