Feedback Requested: Upcoming Major Changes to OpenEMR FHIR API

OpenEMR Development
1

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.

:date: 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.

:arrows_counterclockwise: 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)

:pushpin: 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

:brain: 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.

:writing_hand: 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

:eyes: 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?

:wrench: 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

:brain: Thoughts on this structure? Anyone implementing something similar?

:bar_chart: 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 referral
  • Questionnaire / QuestionnaireResponse – Health assessments
  • Condition, 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

:closed_lock_with_key: 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

:brick: 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.

:pray: What We Need From You

We’d love to hear your feedback on:

  1. Preferred versioning/profile strategy
  2. FHIR write capability configuration
  3. Translation layer design
  4. Server architecture: PHP vs. HAPI
  5. 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

1 Like