A FHIR implementation guide is the rulebook that turns base HL7 FHIR into something two systems can actually agree on. It says which resources a use case uses, which elements must be present, which codes are allowed and how servers and clients should behave, and it ships those rules as computable files as well as web pages.
This guide explains how to read an implementation guide, what sits inside a profile, how FHIR packages and dependencies work, how to author and publish a guide of your own, and where guide projects tend to go wrong.
What is a FHIR implementation guide?
Implementing or authoring a FHIR implementation guide?
Agnotic builds FHIR APIs and apps to published guides, and writes custom profiles and guides for partner exchanges.
A FHIR implementation guide is a published set of rules and computable artifacts, such as profiles, extensions, value sets, CapabilityStatements and examples, that constrain base FHIR for a specific use case, region or program. It is described by an ImplementationGuide resource and distributed as a package that validators and servers can load.
Base FHIR is deliberately loose, so that many use cases can share it. A guide removes that looseness for one purpose. US Core does it for US clinical data, the Da Vinci guides for payer workflows, and national guides for each country's exchange networks.
How do you read an implementation guide?
Read an implementation guide from the outside in: first its scope and conformance pages, then the CapabilityStatements, then the profiles you will implement, and finally the examples. Most guides are generated by the same publishing tool, so their pages follow a familiar layout.
- Home and scope: What the guide covers, its version, its FHIR version and the systems it applies to.
- Conformance pages: General rules, such as how to treat missing data, must-support meaning and security expectations.
- Artifacts index: Every profile, extension, value set, code system, search parameter and operation the guide defines.
- CapabilityStatements: What a conformant server or client must support, including interactions and searches per resource.
- Profiles: One page per profile, with the differential, the full snapshot, constraints and terminology bindings.
- Examples: Sample instances that show how a valid resource looks.
- Downloads: The package file, definitions and validator inputs for use in software.
Check the version you are reading. Guides publish a continuous integration build alongside formal releases, and the CI build may contain changes that no partner implements yet. Pin your work to a released version unless you have agreed otherwise.
What is inside a profile?
A profile is a StructureDefinition that constrains a base resource, such as Patient or Observation, for the guide's use case. It records only what changes in its differential, and tools expand that into a full snapshot that lists every element with its final rules.
- Cardinality: Minimum and maximum occurrences, such as making an identifier required or removing an element.
- Must-support flags: Elements that systems must be able to handle, with the meaning defined on the guide's conformance pages.
- Terminology bindings: The value set an element's codes must, should or may come from.
- Fixed and pattern values: Required codes or values, such as a category that identifies a vital sign.
- Slicing: Rules that split a repeating element into named parts, such as separate systolic and diastolic components.
- Extensions: Additional elements the base resource lacks, each defined in its own StructureDefinition.
- Invariants: FHIRPath constraints that express rules cardinality cannot, such as one of two elements being present.
Developers usually work from the snapshot, because it shows the final shape. When something looks wrong, check the differential to see whether the guide changed the element or inherited it from a parent profile. Profiles can derive from other profiles, so a single element's rules may come from two or three layers, and the snapshot is the only place they appear together.
How do FHIR packages and dependencies work?
FHIR packages bundle a guide's computable artifacts into a versioned file, so software can load the exact rules it implements. Each package declares its FHIR version and the packages it depends on, and tools resolve those dependencies, much like a software package manager.
Packages are published to registries such as packages.fhir.org. A validator or FHIR server configured with a guide's package, and its dependencies, can check resources against the profiles without anyone copying definitions by hand.
- Pin versions: Record the exact package version in configuration and in your test suite.
- Resolve dependencies: Load every dependency at the version the guide declares, since profiles often build on another guide's profiles.
- Watch for conflicts: Two guides depending on different versions of the same base guide can disagree, and the conflict must be resolved deliberately.
- Cache locally: Keep the packages in your build so tests do not depend on a registry being online.
How should a team implement a published guide?
A team should implement a published guide by turning its CapabilityStatement and profiles into a checklist of tests, then building until every test passes. The guide's computable files are the specification; the web pages explain them.
Start with the CapabilityStatement for your role. It lists the resources, interactions, searches and operations a conformant server or client must support. Each line becomes a test case, and the list doubles as the scope for estimates.
Map your data to each profile next. For every required and must-support element, record where the value comes from in your system, how it is coded and what happens when it is missing. Gaps found here are cheaper to resolve than gaps found by a partner.
Validate continuously. Load the guide's package into the FHIR Validator in the build pipeline and validate every example and test response your system produces. Where the guide has an official test kit, run it before asking partners to connect.
Keep a list of deviations. If your system cannot meet a rule yet, record it, tell partners, and plan the fix, rather than letting the gap surface in production.
How do you author an implementation guide step by step?
Authoring an implementation guide follows eight steps, from the use case to a published package. Most authors now write profiles in FHIR Shorthand, which HL7 publishes as a standard, currently version 3.0.0 with mostly normative and some trial-use content, and compile it with SUSHI before running the IG Publisher.
- 1. Define the use case: Write down the actors, exchanges and data each one needs, with real example records.
- 2. Reuse first: Pick base guides to depend on, such as a national core guide, so you profile only what is new.
- 3. Write profiles in FSH: Express profiles, extensions, value sets and invariants in FHIR Shorthand files.
- 4. Compile with SUSHI: Turn the FSH into FHIR resources and the guide's configuration.
- 5. Add narrative: Write the scope, conformance and guidance pages that explain how to use the artifacts.
- 6. Add examples: Create example instances for each profile, including edge cases.
- 7. Run the IG Publisher: Build the website and package, and fix every error and warning the QA report lists.
- 8. Publish and announce: Release a version with a changelog, and publish the package where implementers will find it.
Run the build in continuous integration. Every change should rebuild the guide and its QA report, so broken references and invalid examples are caught at commit rather than at release.
Publishing and versioning an IG
Publishing turns a working build into a stable reference. A guide published through HL7 goes through ballot and a formal publication process, while a guide for a partner network or a single organization can follow a lighter process of its own, as long as versions are clear.
Version every release and say what changed. Implementers need to know whether a new version adds optional elements, which is usually safe, or tightens rules, which can break senders that were valid before. A changelog and a clear version policy prevent surprises.
Keep old versions available. Data exchanged under an earlier version may need to be validated against it for years, and partners will move to new versions on different schedules.
Give the guide an owner and a feedback channel. Implementers will find ambiguities, and a public issue tracker with a named maintainer turns those reports into clarifications in the next release instead of private workarounds at each partner.
Where implementation guide projects go wrong
Implementation guide projects tend to go wrong on scope and versioning rather than syntax. These failure points are worth checking before the first release.
- Profiling everything: Constraining every element of every resource, which makes valid data hard to produce.
- Ignoring base guides: Writing profiles from base FHIR when a national core guide already covers the same data.
- Vague must-support: Flags with no stated meaning, so each partner interprets them differently.
- Example gaps: Profiles with no examples, or examples that fail validation.
- CI builds in production: Systems built to an unreleased build that later changes.
- Unpinned dependencies: Packages pulled at the latest version, so behavior changes without a code change.
- Unreviewed warnings: IG Publisher QA warnings left unresolved until they block a release.
How Agnotic can help
Implementation guides sit at the meeting point of clinical requirements and code. Agnotic Technologies builds FHIR servers, clients and apps to published guides, and authors custom profiles and guides for client exchanges: use case analysis, FSH authoring, SUSHI and IG Publisher builds in CI, example sets and validator integration.
The client and its partners agree the rules. Agnotic turns them into a guide and a package that every party can validate against.
Build to, or write, the right FHIR guide
See how Agnotic builds to published FHIR guides and writes new ones, or browse the FHIR hub.
Related reading on Agnotic
Continue with FHIR interoperability, US Core, first FHIR projects, Questionnaire and FHIR messaging.
