Implementation Guide (FHIR IG)

fhir technical technical fhirinteroperabilityhealthcare
Source: HL7 System: http://hl7.org/fhir Code: ImplementationGuide Reviewed: 18/01/2026 License: CC-BY-4.0

Implementation Guide (FHIR IG)

One-sentence definition: A FHIR Implementation Guide is a published specification that packages profiles, extensions, value sets, and narrative guidance into a deployable conformance artifact — defining exactly how FHIR should be used for a particular use case, jurisdiction, or program.

Full Definition

FHIR is intentionally general. A FHIR resource for a patient or a lab result can carry almost any data in almost any format. That flexibility is only useful in practice when both sender and receiver agree on the same constraints: which fields are required, which code systems to use, which extensions carry meaning. Implementation Guides are the mechanism for recording and distributing those agreements.

An IG bundles together profiles (constrained FHIR resources), extensions (custom data elements), value sets (allowed coded values), capability statements (what servers must support), and human-readable narrative — then publishes them as a coherent, versioned specification. Receivers use the IG to validate incoming resources; senders use it to know what to populate.

IGs are written in FHIR Shorthand (FSH) or raw FHIR JSON/XML, built with the HL7 IG Publisher tool, and distributed as websites and FHIR NPM packages. They are versioned artifacts: US Core 6.x and US Core 7.x are different IGs with different requirements.

Context and Usage

Where This Term Appears

  • ONC certification: EHRs must support specific IGs — US Core, SMART App Launch, Bulk Data — as a condition of Promoting Interoperability certification
  • Da Vinci programs: Each Da Vinci use case (prior auth, coverage discovery, PDEX) produces its own IG
  • Payer-provider contracts: Agreements may specify which IG version a trading partner must conform to
  • FHIR validators: Tools like the HL7 FHIR validator take an IG as input to test resource conformance

Common Usage Examples

In conversation: “The payer is on Da Vinci PDex 2.0 — check which version of US Core that IG pulls in before you start mapping.”

In documentation: “Servers claiming conformance with this IG must support the read and search interactions on Patient as defined in US Core Patient Profile.”

Relationship to Other Terms

  • FHIR — the standard IGs extend and constrain
  • Profile — the primary conformance artifact within an IG; a constrained FHIR resource definition
  • StructureDefinition — the FHIR resource that encodes profiles and extensions within an IG
  • Extension — custom data elements defined and distributed through IGs
  • ValueSet — terminology bindings that IGs package and reference

Common Misconceptions

Misconception: An IG Is Just Documentation

  • Incorrect belief: An IG is a human-readable specification document — useful for developers to read, but not machine-processable.
  • Reality: IGs are machine-processable artifacts distributed as FHIR NPM packages containing FHIR JSON resources. Validators, servers, and test tools consume them programmatically to check conformance.
  • Why it matters: “Read the IG” means understanding the constraints the machine will enforce — not just the narrative text.

Misconception: You Must Implement Everything in an IG

  • Incorrect belief: Claiming conformance with an IG means implementing every profile, extension, and operation it defines.
  • Reality: IGs define conformance levels. A server may support a subset of an IG’s profiles and still claim partial conformance for those profiles it does implement.
  • Why it matters: Misreading conformance scope leads to over-engineering (building unused features) or under-delivery (missing mandatory elements).

Why Implementation Guides Matter

FHIR base resources alone cannot produce interoperability — two systems both claiming to “support FHIR” but using different field conventions still cannot exchange data meaningfully. IGs convert theoretical compatibility into actual interoperability: a shared, versioned agreement that both systems validate against.

Every major US interoperability program — ONC certification, CMS payer APIs, Da Vinci payer-provider exchange — is expressed as one or more IGs. Knowing which IGs apply to a given integration determines what to build.

For how FHIR profiles are authored, validated, and how conformance is tested against an IG, see the canonical reference → FHIR Profiling

Cross-References

  • FHIR — the standard that IGs extend and constrain for specific use cases
  • Profile — the primary conformance artifact within an IG
  • StructureDefinition — the FHIR resource type that represents profiles and extensions in an IG
  • Extension — custom data elements defined and distributed through IGs
  • ValueSet — terminology bindings packaged within IGs

Last reviewed: January 18, 2026 Definition authority: HL7 International Content status: Canonical reference