Well FHIR Modelling Guidelines¶
These are illustrative only. To be reviewed and refined.
Bonus: an LLM prompt to review a FSH file against these guidelines.¶
You are an expert in FHIR modelling, FHIR Shorthand (FSH), and primary care EMR data integration. Your task is to review the provided FHIR,XML,JSON,FSH,... file, assessing it for both general quality and its alignment with the following Well FHIR Modelling Guidelines:
✅ Does the model follow standard FHIR elements where applicable?
❌ Are unnecessary extensions used when a core FHIR element would suffice?
Include the Original – When transforming data (e.g., mapping codes, reformatting names), include the original untransformed value.
✅ If data is transformed, is the original value preserved in a separate element?
❌ Are there cases where transformed data has replaced the original, losing key information?
Model for the Most Granular Use Case – Prefer specific, structured data over broad or loosely defined structures.
✅ Does the model capture data in atomic, structured elements rather than bundling multiple concepts together?
❌ Are there instances where structured fields should be used but free text is relied upon instead?
Normalize Code Systems, But Keep Mappings – Use standard terminologies (SNOMED, LOINC, RxNorm) while retaining original system codes.
✅ Are FHIR standard terminologies used where possible?
✅ Are original system codes stored for traceability?
❌ Are non-standard, EMR-specific codes used without mappings to standard terminologies?
Preserve Clinical Intent – Ensure the data represents the original clinical meaning rather than just the EMR's technical structure.
✅ Does the model faithfully preserve clinical intent across different data sources?
❌ Are there transformations that may misrepresent the clinician's original intent?
Expect Partial and Incomplete Data – Ensure resources handle missing fields and varying levels of detail.
✅ Are required fields minimized to essential elements, allowing incomplete records to be stored?
❌ Are strict validations or required fields forcing artificial completeness?
Model State Transitions Explicitly – Use FHIR status fields (active, entered-in-error, etc.) and provenance metadata.
✅ Does the model correctly use FHIR status fields and provenance tracking?
❌ Are state changes implicit, undocumented, or missing?
Use References Instead of Duplication – Link related resources instead of copying data.
✅ Are FHIR references used to connect resources appropriately?
❌ Is data duplicated across multiple resources, creating inconsistency risks?
Prefer Structured Over Unstructured Data – Store data in discrete fields rather than free text unless unstructured data is needed for context.
✅ Is structured data extracted and used wherever possible?
✅ If structured data is extracted, is the original unstructured data still included for reference?
❌ Are important details stored only as free text when they could be structured?
Consider Future Expansion – Model resources to accommodate evolving national standards and regional variations.
✅ Is the model flexible enough to support future growth and additional data elements?
❌ Are design choices overly rigid, limiting future extensibility?
Well FHIR Modelling Guidelines¶
"Be Normal" – Use core FHIR elements whenever possible; only extend when necessary.¶
Why? Because sticking to the standard makes it easier to map data from different EMRs into a common structure and ensures compatibility with other FHIR-based systems. And even when using extensions, validate whether a well-known one already exists before creating a new/duplicated one (e.g. extensions for Canadian HINs already exist in the pan-Canadian space)
"Include the Original" – If transforming code systems and property values (e.g., mapping codes, reformatting names), include the original untransformed value, as well as the system that generated the original data.¶
Why? Because transformations are lossy. Retaining original values allows applications to use standardized data where possible while still accessing the source system's details when precision is needed, for reconciliation, auditing, and system-specific behavior.
"Preserve Clinical Intent" – Ensure that modeled data reflects the original clinical meaning rather than just technical structures.¶
Why? Because EMRs often store equivalent concepts in different ways (e.g., allergies as free text vs. structured lists). The goal is to capture what the provider meant, not just what the system stored.
"Expect Partial and Incomplete Data" – Design resources to handle missing fields, optional elements, and varying levels of detail from different EMRs.¶
Why? Because primary care EMRs have inconsistent data capture practices. Applications must gracefully handle gaps without assuming completeness.
"Use References Instead of Duplication" – Store relationships between resources (e.g., linking Conditions to Encounters) rather than copying data.¶
Why? Because FHIR is designed for linked data, and duplicating values leads to inconsistencies and synchronization issues. Note that this guideline is intended to prevent denormalization in the FHIR translation. If the source system has multiple copies of the same entity (provider, allergy, etc), it is not expected that we would try to match them in general.
"Consider Future Expansion" – Model resources to accommodate evolving national standards and regional variations.¶
Why? Because primary care data needs will change, and a rigid model will limit future growth and adaptation.