Skip to content

FHIR Modelling Process

Version 0.1 – March 27, 2025

Overview

All changes to the Polaris FHIR specification—including new or modified resources, profiles, extensions, value sets, or other artifacts—must follow this lightweight, collaborative, standards-aligned process. This process is led by Shawn Vincent, with the goal of producing a practical, interoperable, and implementable Well-wide specification that supports integration needs and reduces rework.

Triggers for FHIR Modelling

  • Primary: A concrete integration requirement driven by an active implementation (such as CPAR, CII, or other integration needs).
  • Secondary: An internal modelling initiative, approved by the organization to support anticipated future needs.
    (We prefer to minimize speculative work.)

All changes must be driven by a clear external or organizational requirement.

Standards Alignment

Changes must conform to CA-Core+ profiles wherever feasible.

Any deviations must be justified and documented.

Reuse of existing FHIR elements and extensions is prioritized over creating custom extensions.

Design Principles

  • Reuse existing FHIR elements, CA-Core profiles, and EMR-provided FHIR work wherever feasible.
  • Implementability is paramount — specifications must be practical and efficient for real-world integration and development.
  • Strive for backwards compatibility. Any breaking changes must be:
    • Deeply considered and justified
    • Reviewed with impacted stakeholders
    • Accompanied by clear guidance for downstream rework

Governance & Roles

Each change must include input from the Polaris FHIR Working Group, including the following stakeholders:

  • Polaris Application Prime (Dan Black): Ensures the model supports the specific Polaris application use case.
  • EMR Stakeholder Prime (Rebecca Skitch): Validates mapping and feasibility from the perspective of the target EMRs.
  • FHIR Standards Lead (Raman Dhanoa): Verifies alignment with core FHIR standards and CA-Core.
  • Polaris Architecture (Aaron Aston): alignment with Polaris FHIR architecture decisions.
  • Ownership, coordination, facilitation (one throat to choke: owns final decisions) by Shawn Vincent (the one throat to choke).
  • Sponsored and supported by Peter Cresswell.

This group should have access to code, existing documentation, FHIR sample output, and implemented FHIR specs from the target EMRs, as well as any available integration documentation.

Possible future addition: Form a broader FHIR expert group within Well for asynchronous input and review.

Workflow & Communication

  • Weekly FHIR Working Group Meeting (~1 hour): Core venue for planning, design, and review.
  • Breakout Sessions: Scheduled as needed for focused technical or stakeholder alignment work.
    (Try to avoid if possible and minimize attendance. People are busy.)

Formal Versioning

  • All FHIR artifacts must be versioned (profiles, extensions, value sets, etc.)
  • Maintain clear changelogs, including rationale and impact

Communication

  • All changes and new versions must be announced to affected teams
  • Include summaries of changes, expected impact, and timelines for adoption

Outputs

  • Design Documentation: Rationale, discussions, and decisions tracked in Confluence
  • FSH Specifications: Committed to Git, with matching MedPlum definitions installed in a test instance (ASAP)
  • Developer-Facing Docs: Easy-to-consume documentation for Well Health developers (ASAP)
  • Ongoing Reporting:
    • Visibility into current modelling activity
    • Version history and upcoming changes
    • Tracking of unresolved issues or change requests

Version History

  • v0.1 – Initial draft circulated for comment