FHIR Genomics Reporting: A Practical Implementation Guide

The HL7 Genomics Reporting Implementation Guide is the authoritative starting point for FHIR genomics reporting. Start by choosing the IG package version, confirming your code systems (LOINC, HGVS), and mapping your lab outputs to the GenomicReport and Observation profiles it defines. Every credible pharmacogenomics reporting pipeline, from CPIC-aligned clinical decision support to white-label lab infrastructure like SignalPGx, traces back to this specification.

Your first three moves as an implementer should look like this:

• Pin down the FHIR version and IG package (R4, R4B, or R5) your EHR and lab systems can actually support today, not the version you wish you had.
• Confirm which code systems you will use for observable codes and variant nomenclature, typically LOINC for observations and HGVS for variant descriptions.
• Map out where genomic data needs to surface in your EHR and which CDS rules will consume it, before you write a single profile.

If your team needs production-ready pharmacogenomics reporting rather than a from-scratch build, vendor platforms like SignalPGx already implement these mappings, which shortens the distance between a validated genotype and a physician-reviewed report.

Key Takeaways

FHIR genomics reporting succeeds when implementers follow the Genomics Reporting IG's profile structure, invest in genotype-to-phenotype translation logic, and preserve traceability through derivedFrom and hasMember relationships.

Table of Contents

• What Does FHIR Genomics Reporting Cover, and Who Needs It?
• Which Core FHIR Resources Do You Need to Implement?
• How Do You Map Genotype to Phenotype to Clinical Implication?
• Why Do hasMember and derivedFrom Relationships Matter?
• What Belongs on Your Implementation Checklist?
• What Does a PGx GenomicReport JSON Instance Actually Look Like?
• Which IG Version and Extension Packs Should You Pin?
• How Do You Surface Genomic Data in the EHR Without Triggering Alert Fatigue?
• How Does SignalPGx Support FHIR Genomics Reporting in Practice?
• What Implementers Consistently Get Wrong About This Work
• Ready to Move From FHIR Profiles to a Live PGx Report?
• Sources
• FAQ

What Does FHIR Genomics Reporting Cover, and Who Needs It?

The Genomics Reporting IG standardizes structured data, not lab operations. It defines how to represent variants, genotypes, diplotypes, and therapeutic implications as FHIR resources, but it deliberately stays out of ordering, specimen routing, and delivery pipelines, which the IG's own documentation treats as separate concerns left to each implementer's operational systems.

That scope boundary matters because teams often assume the IG will solve their entire workflow. It will not. It covers four broad reporting domains:

• Pharmacogenomics (PGx) reporting, including diplotypes, phenotypes, and medication implications.
• Somatic (oncology) variant reporting, where tumor findings drive treatment implications.
• HLA typing and genotype reporting for transplant and immunology use cases.
• General genomic reporting for germline findings outside a specific specialty.

Four groups of implementers will spend the most time inside this specification. Laboratory informatics engineers translate variant call files into structured FHIR resources. Health system informaticists design how genomic data lands in the clinical record. EHR integrators build the interfaces between lab systems and platforms like Epic or Cerner. CDS developers write the rules that turn a diplotype into an actionable alert at the point of prescribing.

Which Core FHIR Resources Do You Need to Implement?

Six resource types carry nearly all the weight in a genomics reporting build. Understanding what each one is for, rather than treating them as interchangeable containers, prevents the single most common implementation mistake: cramming interpretive conclusions into the wrong resource.

1. GenomicReport packages the finished, physician-reviewed output. It aggregates the variant findings, therapeutic implications, and narrative conclusions into one referenceable unit, functioning as a specialized profile built on DiagnosticReport.
2. GenomicStudy groups the analyses and sequencing runs behind a report. It carries study-level metadata, such as which sequencing method or panel produced the results, and lets a single report reference multiple constituent analyses through GenomicStudy.analysis.
3. DiagnosticReport remains the parent resource type that GenomicReport specializes. If your EHR already has DiagnosticReport ingestion pipelines, that infrastructure carries over directly.
4. ServiceRequest represents the order that triggered the genomic analysis in the first place, linking the report back to the ordering clinician and original clinical question.
5. Observation profiles carry the actual findings: Variant, Genotype, Haplotype, and Diplotype observations describe what was found, while TherapeuticImplication observations describe what it means clinically.
6. MolecularSequence stores raw sequence data. HL7 guidance is explicit that this resource is not the right home for interpretive clinical conclusions; the FHIR genomics overview recommends deferring to Genomics Reporting IG profiles for anything a clinician needs to act on.

Pro Tip: Do not let your data engineers default to MolecularSequence because it feels like the "genomics resource." Reserve it for raw sequence archival or specialized bioinformatics use cases, and route every interpretive finding through the Observation profiles instead.

The distinction between GenomicReport and GenomicStudy trips up a lot of first-time implementers. Think of GenomicStudy as the laboratory's methodology record, what was sequenced, how, and when, while GenomicReport is the clinical output built from that methodology. A single study can feed multiple reports over time, particularly under a living reanalysis model where new evidence changes the interpretation without requiring a new sequencing run.

How Do You Map Genotype to Phenotype to Clinical Implication?

Pharmacogenomics reporting in FHIR follows a four-step chain: genotype Observation, diplotype Observation, phenotype Observation, and TherapeuticImplication Observation. Each step is its own resource instance, linked through derivedFrom, and the PGx-specific user guide in the IG walks through this pattern using a worked eMERGE example.

Here is the practical breakdown implementers need:

• A genotype Observation records the raw allele call for a gene, for example CYP2D6.
• A diplotype Observation combines two allele calls into a single genotype designation, such as *1/*4.
• A phenotype Observation translates that diplotype into a functional category (poor metabolizer, normal metabolizer, ultrarapid metabolizer), and this translation step is where local rule tables do the real work.
• A TherapeuticImplication Observation ties the phenotype to a specific medication and a clinical recommendation, often referencing a medication-assessed component that names the drug in question.
• Medication recommendations that require an action, rather than just an observation, use a Task resource following the MedicationRecommendation pattern the IG defines.

Genotype to phenotype translation is rarely a simple lookup table you can hard-code once. CPIC guidance changes as evidence accumulates, which is why the same phenotype call for the same diplotype can shift between guideline versions. Informatics literature on genomics integration consistently identifies this translation layer as the place where complexity actually lives, not in the FHIR resource shapes themselves. Aligning your phenotype tables with CPIC, FDA, and DPWG guidance takes ongoing maintenance, not a one-time mapping exercise.

Document every provenance decision inside the Observation itself. A TherapeuticImplication conclusion string should state which guideline version generated the recommendation and which medication coding system (RxNorm is common, but not universal) you used, so a reviewing pharmacist or a downstream auditor can trace the logic without opening a separate spreadsheet.

Why Do hasMember and derivedFrom Relationships Matter?

Downstream systems that only read DiagnosticReport.result will miss anything not explicitly linked there, which is exactly why hasMember and derivedFrom relationships are not optional metadata. They are the mechanism that lets a receiving system reconstruct the full clinical picture instead of stopping at the surface-level report.

The IG's guidance on general genomic reporting is direct about this: GenomicImplication observations must reference their supporting variant or genotype findings through derivedFrom, preserving the traceability a clinician needs to validate why a specific implication was generated. A pharmacist reviewing a warfarin sensitivity flag should be able to follow that link straight back to the CYP2C9 and VKORC1 genotype calls that produced it.

Three practical steps keep this navigable in production:

1. Ensure every TherapeuticImplication Observation carries derivedFrom references to each contributing genotype or diplotype Observation, even when multiple genotypes feed a single implication.
2. Populate DiagnosticReport.result with every clinically relevant Observation, not just a summary subset, since many consuming systems never traverse beyond that list.
3. Design your query layer to support REST search patterns like Observation?based-on=ServiceRequest/123 or DiagnosticReport?_include=DiagnosticReport:result so consumers can pull grouped results, variants, implications, and Tasks in a single retrieval rather than chasing references one at a time.

Architecture that anticipates many-to-many relationships, where one implication draws on several variants, avoids a rebuild later. Retrofitting traceability after a system already assumes one-to-one links is significantly more expensive than designing for it up front.

What Belongs on Your Implementation Checklist?

A genomics reporting build succeeds or fails on sequencing the work correctly. Here is the order that actually holds up under production pressure:

1. Freeze your code systems first. Decide on LOINC for observable codes, HGVS for variant nomenclature, ClinVar references where relevant, and your medication coding system, before building profiles around them. Changing code systems mid-project cascades into every downstream mapping table.
2. Map lab outputs to IG profiles. Decide explicitly what gets stored as structured FHIR data versus what stays referenced as an external file (VCF, BAM). Storing everything as FHIR resources is rarely necessary or efficient.
3. Build genotype-to-phenotype translation tables with a CPIC alignment strategy. Assign ownership for keeping these tables current as guidelines revise, and version them explicitly.
4. Plan clinical validation with pharmacists and clinicians before go-live. Multidisciplinary review catches translation errors that a purely technical FHIR review will miss entirely.
5. Create example JSON bundles and automated validation tests, covering both structural validation (does it conform to the profile) and semantic validation (does the clinical logic make sense).
6. Address security, privacy, and governance items explicitly, including HIPAA and GDPR compliance, consent tracking, and an audit trail for every report revision.

Pro Tip: Build your validation test suite around real edge cases, like a patient with three prior genotype results and a new reanalysis, before you build it around the happy path. Edge cases are where derivedFrom links and Task statuses actually break.

The UF Health implementation documented in a published Epic integration study required exactly this kind of bespoke mapping and translation work, and a multidisciplinary team, to get PGx data flowing correctly into genomic indicators. Labs launching their own reporting service can shortcut a meaningful part of this checklist by working from an existing operational playbook rather than reinventing each governance step from scratch.

What Does a PGx GenomicReport JSON Instance Actually Look Like?

A worked example clarifies more in five minutes than a page of profile definitions. The PGx user guide's eMERGE example shows a DiagnosticReport (profiled as GenomicReport) at the top level, with result references pointing to a set of child Observations, and Task resources hanging off the TherapeuticImplication for anything requiring a medication action.

The table below breaks down which fields are required versus recommended when you adapt this pattern to your own gene panel.

Adapting this pattern to a local gene panel means three things in practice: mapping your panel's variant codes to accepted nomenclature, choosing a consistent medication coding system across every TherapeuticImplication, and adding provenance metadata (assay version, guideline version, review date) so a reanalysis six months later has something concrete to compare against. Teams building this mapping logic themselves often find it useful to study how a full genotype-to-guidance pipeline handles the handoff from raw call to physician-facing recommendation.

Which IG Version and Extension Packs Should You Pin?

FHIR R4 remains the most widely deployed version for genomics reporting today, with R4B and R5 packages available for teams building against newer EHR integrations. The Genomics Reporting IG publishes version-specific packages, so confirm which one your EHR vendor's FHIR server actually supports before committing.

• Check whether your EHR's FHIR server explicitly supports the IG package version you plan to build against, rather than assuming R4 compatibility across the board.
• Common extension packs layer in terminology bindings and structural extensions the base IG references; evaluate whether you need the full pack or just the specific extensions relevant to PGx.
• Pin your IG package version in production and test upgrades in a staging environment before adopting a new release, since profile constraints do shift between versions.

Treat IG version selection as a dependency to manage deliberately, not a default you inherit from whatever tutorial you followed first.

How Do You Surface Genomic Data in the EHR Without Triggering Alert Fatigue?

Two integration patterns dominate real deployments: triggering CDS directly off raw Observation resources, or triggering off a derived genomic indicator that summarizes the clinical status. Direct-Observation triggering is simpler to build but tends to fire on every data point, which is how alert fatigue starts. The indicator pattern requires more upfront translation work but scales better because the CDS rule engine reacts to a stable, pre-processed signal rather than raw genomic complexity.

• Genomic indicators (a simplified flag like "poor metabolizer, avoid standard dosing") reduce the surface area CDS rules need to evaluate.
• TherapeuticImplication Observations and Task references both work as CDS triggers; Task references are useful when the recommendation requires a specific action rather than a passive alert.
• Legacy results need retroactive processing if you are converting an existing CDS rule base to indicator-based triggers, which is exactly the migration UF Health documented.

Pro Tip: Track CDS interaction metrics before and after any migration to indicator-based triggering. The UF Health team's shift to genomic indicators drove a 112% increase in clinician interactions with genomic alerts, and that kind of before/after measurement is the only way to know if your rule maintenance effort is paying off.

Operational maintenance does not end at go-live. Someone needs explicit ownership of updating translation rules as CPIC guidance revises, and that ownership question belongs on your governance checklist, not left as an assumption. Practical patterns for wiring this into CDS Hooks and your EHR's decision support engine are covered in more depth in a dedicated integration guide.

How Does SignalPGx Support FHIR Genomics Reporting in Practice?

SignalPGx builds pharmacogenomics reporting software specifically for clinical laboratories, converting genotype and medication history data into physician-reviewed, evidence-based PGx reports rather than leaving that translation work entirely to each lab's internal team.

The platform's HL7/FHIR integration handles the EHR connection points this article has walked through: genomic indicators, TherapeuticImplication mapping, and report delivery into existing clinical workflows. A few capabilities map directly onto the implementation challenges above:

• Medication intelligence simulation models drug response and risk before a report reaches a clinician, which supports the genotype-to-implication translation work every PGx build requires.
• Living reanalysis automatically updates recommendations as CPIC and other guidelines evolve, addressing the ongoing maintenance burden that static translation tables create.
• White-label infrastructure lets a lab deploy branded PGx reporting within 5 to 7 days rather than building the full IG mapping and validation pipeline from scratch.
• Compliance and audit trail features cover HIPAA and GDPR requirements alongside medical-director review, which matters for the governance checklist any production deployment needs.

What Implementers Consistently Get Wrong About This Work

The conventional advice treats FHIR genomics reporting as a profile-mapping exercise: pick the right resources, validate against the IG, ship it. That advice is not wrong, but it is incomplete in a way that burns real project timelines. The UF Health implementation didn't stall on FHIR structure. It stalled, and then succeeded, on the translation layer between raw genotype calls and clinical action, the genotype-to-phenotype tables, the CDS rule conversion, the multidisciplinary review.

Most teams underestimate how much of this project is organizational rather than technical. A pharmacist needs to sign off on your phenotype assignments. A clinical informaticist needs to own the CDS rule maintenance schedule. Nobody's FHIR server certification solves that problem.

If you prioritize one thing first, prioritize the translation table and its governance, before you write a single line of profile-conforming JSON. The resources themselves are well documented and stable. The judgment calls about how a diplotype becomes a phenotype, and how that phenotype becomes an alert a clinician actually trusts, are where projects either compress into weeks or stretch into years.

Ready to Move From FHIR Profiles to a Live PGx Report?

Building genotype-to-phenotype translation tables, CPIC alignment logic, and CDS integration in-house typically takes a multidisciplinary team months to validate properly, the exact challenge this article just walked through. SignalPGx gives laboratories that same translation and integration layer as deployable infrastructure instead of a from-scratch build.

The platform handles the genotype-to-implication mapping, keeps recommendations current through living reanalysis as CPIC and other guidelines change, and connects to your EHR through the same HL7/FHIR patterns detailed above. Labs get a white-label reporting service, physician-reviewed and audit-ready, without maintaining the translation tables and CDS rule sets internally. If your team is evaluating whether to build this mapping layer yourselves or deploy it, book a demo of SignalPGx's white-label PGx reporting and see how the FHIR integration maps onto your existing lab and EHR setup.

FAQ

Should I Use MolecularSequence or Observation Profiles for PGx Reports?

Use Observation profiles for anything a clinician needs to act on. HL7's FHIR genomics guidance is explicit that MolecularSequence is meant for raw sequence data, not interpretive clinical conclusions.

What Is the Difference Between GenomicReport and GenomicStudy?

GenomicReport packages the finished clinical output, findings and conclusions, while GenomicStudy holds study-level metadata about the sequencing analyses that produced those findings.

Why Do I Need derivedFrom Links in My PGx Observations?

derivedFrom links preserve traceability, letting a downstream consumer trace a TherapeuticImplication back to the exact genotype or variant Observations that generated it, which the IG's general reporting guidance requires for validation.

How Do I Avoid Alert Fatigue When Triggering CDS From Genomic Data?

Trigger CDS from derived genomic indicators rather than raw Observations wherever possible; that approach reduces the CDS engine's exposure to raw genomic complexity while remaining tied to the underlying clinical signal.

Can Vendor Platforms Handle FHIR Genomics Reporting Instead of a Custom Build?

Yes. Platforms like SignalPGx already implement HL7/FHIR-integrated PGx reporting with living reanalysis and white-label deployment, which can shorten the path to production compared with building the full translation and mapping layer in-house.

Recommended

• Genotype to Phenotype: A Clinical PGx Reporting Guide
• PGx in the EHR with FHIR & CDS Hooks | SignalPGx
• From Genotype to Guidance: The PGx Pipeline | SignalPGx
• Living PGx Reports: Keeping Guidance Current | SignalPGx