ImplementationGuide — The root of a FHIR IG

US Core, IPS, FR Core, MIO, IPS-AU: every Implementation Guide publishes a root ImplementationGuide resource that describes the contents, dependencies and table of contents of a FHIR package.

Purpose

A FHIR Implementation Guide (IG) is a deliverable package bundling profiles (StructureDefinition), terminologies (ValueSet, CodeSystem), examples, extensions and narrative documentation. ImplementationGuide is the root resource that describes the package: its dependencies, its npm-FHIR packageId, its target FHIR version, its license.

HL7's reference tool IG Publisher consumes this root, walks the listed artefacts, and generates both the HTML website of the IG (the page sub-tree) and the distributable npm-FHIR package hl7.fhir.<realm>.<name>.

Key fields

Reference IGs

• US Core — hl7.fhir.us.core — the US pivot profile for ONC.
• IPS UV — hl7.fhir.uv.ips — International Patient Summary.
• FR Core — hl7.fhir.fr.core — the French ANS profile.
• NL Core / Nictiz — Dutch profile.
• UK Core — hl7.fhir.uk.core — NHS Digital profile.
• IHE PCC mCSD, mACM... — IHE IGs for reference technical profiles.
• SDOH Clinical Care — Social Determinants of Health (HL7 US).
• CARIN BB — Consumer-Directed Payer Data Exchange.

JSON example

Skeleton of a US Core ImplementationGuide, version 6.1.0:

{
  "resourceType": "ImplementationGuide",
  "id": "hl7.fhir.us.core",
  "url": "http://hl7.org/fhir/us/core/ImplementationGuide/hl7.fhir.us.core",
  "version": "6.1.0",
  "name": "USCoreImplementationGuide",
  "title": "US Core Implementation Guide",
  "status": "active",
  "experimental": false,
  "date": "2026-05-14",
  "publisher": "HL7 International - Cross-Group Projects",
  "packageId": "hl7.fhir.us.core",
  "license": "CC0-1.0",
  "fhirVersion": ["5.0.0"],
  "dependsOn": [{
    "uri": "http://terminology.hl7.org/ImplementationGuide/hl7.terminology",
    "packageId": "hl7.terminology",
    "version": "5.5.0"
  }],
  "definition": {
    "resource": [
      { "reference": { "reference": "StructureDefinition/us-core-patient" }, "name": "US Core Patient Profile", "exampleBoolean": false },
      { "reference": { "reference": "StructureDefinition/us-core-condition" }, "name": "US Core Condition Profile", "exampleBoolean": false },
      { "reference": { "reference": "ValueSet/us-core-clinical-note-type" }, "name": "US Core Clinical Note Type", "exampleBoolean": false },
      { "reference": { "reference": "Patient/example" }, "name": "Example Patient", "exampleBoolean": true }
    ],
    "page": {
      "nameUrl": "toc.html",
      "title": "Table of Contents",
      "generation": "html"
    }
  }
}

Common pitfalls

• Non-npm-compliant packageId — must be lowercase, no underscore, format vendor.fhir.realm.name.
• Missing dependsOn — an IG that reuses THO (HL7 Terminology) CodeSystems MUST declare the dependency so IG Publisher can resolve codes.
• Wrong FHIR version — R4 (4.0.1) and R5 (5.0.0) IGs are not interoperable: servers read fhirVersion before loading anything.
• Profile with incompatible constraints — a child profile that relaxes a parent's constraint is an invalid derivation, rejected by IG Publisher.
• Confusing IG and npm package — the IG is metadata, the npm-FHIR package (npm install --registry=https://packages.simplifier.net) is the physical deliverable.

Related resources

• StructureDefinition — profile/Resource/Extension described by the IG.
• ValueSet, CodeSystem — bundled terminologies.
• OperationDefinition — business operations described by the IG.
• CapabilityStatement — IG-conformant server capability.