FHIR R4 Symptoms Implementation Guide
1.0.0 - STU 1 International flag

FHIR R4 Symptoms Implementation Guide, published by HL7 International / Clinical Interoperability Council. This guide is not an authorized publication; it is the continuous build for version 1.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/fhir-symptoms-ig/ and changes regularly. See the Directory of published versions

Plain Language Summary goes here

IG Home

Official URL: http://hl7.org/fhir/uv/symptoms/ImplementationGuide/hl7.fhir.uv.symptoms Version: 1.0.0
IG Standards status: Trial-use Active as of 2026-04-01 Maturity Level: 2 Computable Name: SymptomsDataStandards

Overview

Purpose and Scope

The purpose of this implementation guide is to standardize the representation and exchange of patient-reported symptoms using FHIR R4 resources. The absence of standardized definitions and formats for symptoms data currently hinders effective sharing across providers. This initiative aims to decrease missed, delayed, or inaccurate diagnoses by supporting the standardized exchange of symptom data.

Symptoms in the context of this guide refer to subjective observations reported by patients or their caregivers about changes in their health status. This guide focuses on capturing what patients report about their experiences, which may include both what clinicians would classify as true symptoms (subjective experiences like pain or fatigue) as well as signs (objective findings that patients observe about themselves, such as a rash or swelling). The semantic intent is to capture the patient’s perspective of their health concerns as they report them, recognizing that patients may not distinguish between symptoms and signs in the way healthcare professionals do.

This implementation guide provides FHIR profiles that structure patient-reported symptom data for exchange across visits and health systems. By standardizing how systems represent key symptom attributes, including severity, onset, duration, location, quality, and other characteristics, this guide supports the recognition of symptom patterns and ultimately supports more informed diagnostic decision-making to improve patient outcomes.

References

[1] Singh H, Meyer AN, Thomas EJ. The frequency of diagnostic errors in outpatient care: estimations from three large observational studies involving US adult populations. BMJ Qual Saf. 2014;23(9):727-731. doi:10.1136/bmjqs-2013-002627

[2] Newman-Toker DE, Nassery N, Schaffer AC, et al. Burden of serious harms from diagnostic error in the USA. BMJ Qual Saf. 2024;33(2):109-120. doi:10.1136/bmjqs-2021-014130

[3] Liberman AL, Newman-Toker DE. Symptom-Disease Pair Analysis of Diagnostic Error (SPADE): a conceptual framework and methodological approach for unearthing misdiagnosis-related harms using big data. BMJ Qual Saf. 2018;27(7):557-566. doi:10.1136/bmjqs-2017-007032

Intended Audience and System Capabilities

This guide is intended for health information systems that have the capability to expose symptom data as discrete, structured FHIR elements. This includes:

  • Electronic Health Record (EHR) systems
  • Patient-facing applications and patient-reported outcome platforms
  • Care coordination platforms
  • Clinical decision support systems
  • Data analytics and population health systems

Important Note on Implementation Variability: While this guide defines profiles with discrete elements for representing detailed symptom information, implementers should recognize that system capabilities vary. Some systems may have robust structured data capture for symptoms and can populate all discrete elements defined in the profiles. Other systems may have more limited capabilities and may only be able to return symptom information as narrative text in the Observation.value element, with minimal use of the other discrete profile elements. Both approaches are valid implementations of this guide, though systems with more granular data capture will provide richer information to support clinical decision-making.

What This Guide Covers

  • Standardized FHIR profiles for representing patient-reported symptoms
  • Guidance on capturing symptom attributes as reported by patients (severity, onset, timing, location, quality, etc.)
  • Exchange patterns for sharing symptom information across care settings
  • Terminology bindings to support semantic interoperability
  • Use cases demonstrating symptom documentation and exchange scenarios

What This Guide Does Not Cover

  • Clinical signs obtained through provider examination or diagnostic testing (unless reported by the patient themselves)
  • Diagnostic conclusions or clinical interpretations
  • Prescriptive guidance on clinical symptom assessment methodologies
  • Requirements for specific user interfaces or data capture workflows

From Pre-Coordinated to Post-Coordinated: Best Practices for Symptom Data Exchange

Electronic health records (EHRs) and other clinical systems sometimes capture and store symptoms as pre-coordinated concepts and/or text, meaning one code combines multiple details—for example, “abdominal pain” includes both the symptom and the body site.

For data exchange, this Implementation Guide (IG) recommends a post-coordinated approach. This means breaking down the combined code (decomposition) so the symptom goes in observation.value, while related details—such as body site—are recorded in separate fields. This structure improves flexibility and supports consistent interoperability across systems. See the following table which provides examples of Pre-Coordinated code versus the Post-Coordinated combinations.

It is still necessary for the original pre-coordinated concept to be included in exchange and the FHIR CodableConcept structure allows this by including multiple Codings. Our recommendation is that a system send the post-coordinated code as one Coding and also send the original concept as another Coding with the Coding.userSelected element set to 'true'.

Pre-coordinated coding.code Pre-coordinated coding.display Map to Post-coordinated value.coding.code Post-coordinated value.coding.display Post-coordinated bodySite coding.code Post-coordinated bodySite coding.display
51197009 Stomach cramps (finding)   55300003 Cramp (finding) 69695003 Stomach structure (body structure)
53430007 Pain of breast (finding)   22253000 Pain (finding) 76752008 Breast structure (body structure)
25064002 Headache (finding)   22253000 Pain (finding) 69536005 Head structure (body structure)
279039007 Low back pain (finding)   22253000 Pain (finding) 37822005 Structure of back of abdominopelvic segment of trunk (body structure)
30473006 Pain in pelvis (finding)   22253000 Pain (finding) 12921003 Structure of pelvis (body structure)
23924001 Tight chest (finding)   299954009 Tightness sensation (finding) 51185008 Thoracic structure (body structure)
57676002 Pain of joint (finding)   22253000 Pain (finding) 39352004 Joint structure (body structure)
21522001 Abdominal pain (finding)   22253000 Pain (finding) 818983003 Abdomen (body structure)
29857009 Chest pain (finding)   22253000 Pain (finding) 51185008 Thoracic structure (body structure)

NOTE ON SNOMED CT USAGE: Throughout this guide, we recommend and use SNOMED-CT codes. Work is underway to include the common symptoms code in the IPS SNOMED value set which would then be accessible to all.

Content and Organization

This implementation guide (and the menu for it) is organized into the following sections:

  • Background - Supporting informative pages that do not set conformence expectations
    • Reading this IG points to key pages in the FHIR spec that must be understood in order to understand this guide
    • Use Cases gives examples of symptoms and how they are recorded using the profiles in the guide
    • Projects and Participants identifies the individuals and organizations involved in developing this implementation guide
  • Specification - Pages that set conformance expectations
  • FHIR Artifacts
    • Artifacts points to the complete list of artifacts defined in this guide
    • Terminology lists all of the value sets that are defined in this guide
  • Support - Links to help with the use of this guide
    • Discussion Forum is a place to ask questions about the guide and discuss potential issues
    • Project Home includes information about project calls, agendas, past minutes, and instructions on how to participate
    • Project Dashboard shows new and historical issues that have been logged against the specification
    • Propose a Change allows formal submission of requests for change to the specification
  • Change Log lists all of the changes between versions of the guide

Dependencies

Implementation GuideVersion(s)Reason
FHIR Extensions Pack5.2.0

Automatically added as a dependency - all IGs depend on the HL7 Extension Pack

FHIR R4 package : Core4.0.1Imported by HL7 Terminology (THO) (and potentially others)
FHIR Tooling Extensions IG0.9.0Imported by OpenEHR Base package (and potentially others)
HL7 Terminology (THO)7.1.0

Automatically added as a dependency - all IGs depend on HL7 Terminology

7.0.1Imported by OpenEHR Base package (and potentially others)
OpenEHR Base package0.1.0-snapshot

Used to display the OpenEHR archetypes in a FHIR IG.

IP Statements

This publication includes IP covered under the following statements.