FHIR Implementation Guides

Introducing FHIR Implementation Guides

FHIR is a platform specification. It describes a general set of capabilities that can be used to solve many healthcare data exchange problems. Because FHIR is used for all sorts of problems, in many jurisdictions, using a variety of architectures and information exchange patterns, the FHIR specification is very general and there are many ways to solve a problem. For this reason, implementers must make choices, and for particular solutions to be interoperable, the implementations must make the same set of choices.

FHIR Implementation guides (IG) are used to describe how FHIR is used in a particular context. Many IGs fit into one of these 3 categories:

1. Jurisdication Base: Describes based rules for using FHIR in a jurisdiction (usually a country specific set of rules)
2. Application Solution: Describes how FHIR is used to solve a particular problem (e.g. EHR App access)
3. Domain Guide: Describes the proper way to represent particular content in FHIR (e.g. how to properly represent the breast cancer diagnostic process)

Note that individual IGs may cross categories, or not fall into any of these major categories.

Finding Implementation Guides

The FHIR Foundation maintains a central registry of IGs. Any publicly available IG may be registered (see instructions), and authors are encouraged to do so.

The FHIR Foundation also maintains a general FHIR repository, which contains a finer grained set of information. This registry includes - but is not limited to - the conformance artifacts (extensions, profiles, value sets etc) found in the implementation guides published by fhir.org and hl7.org, and authors are encouraged to keep the general registry up to date. If the content in the registry is registered through the IG upload process, the registry will provide a link to the IG where the resource is published.

In addition, implementation guides may be found using google etc.

Using Implementation Guides

The primary use of an implementation guide is to read it online.

Most guides offer a download facility so that that it can be used locally while offline. Note, though, that guides that reference each other will reference back to the web location, not the local download copy.

In addition, guides include, as part of their content, a set of files that are suitable for use by validation and code generation tooling. Tools that support FHIR IGs know where to find this tooling when provided with the location (root URL) of the IG (whether a local copy, or on the web).

FHIR IGs have NPM package descriptions, so that IG dependency may be managed using NPM.

Authoring FHIR Implementation Guides

The general workflow for authoring an implementation guide is as follows:

• Getting Started
  • Describe your Implementation Guide (IG), it's scope, and it's canonical URL
    • for HL7 guides, this will be hl7.org. for other guides, it may be fhir.org, ihe.org etc
  • choose a template for your IG
  • create an initial implementation Guide resource with no content
  • set up version control for your IG
  • Build the IG using the IG publisher
    • if the github repository is public, set up auto-publishing so that the latest version of the guide is always found on build.fhir.org

• Developing Content
  • add conformance resources (see below) that describe your implementation
  • write narrative (html, xhtml, or markdown according to taste)
  • add examples, images, etc to fill out the implementation guide

• Publishing once Complete
  • milestone builds should be published to the canonical location (copying the set generated html files around)
  • the canonical location layout should generally follow the FHIR version publication pattern
  • Content to be published on hl7.org or fhir.org must be generated via the FHIR IG publisher

Typically, an IG will iterate between developing and publishing many times over it's time as it is drafted, and then consensus builds.

Kinds of content in a typical Implementation Guide

Note that Authors should keep Best practice Guidelines for IGs in mind while developing their IGs

Tooling Support for Authoring FHIR Implementation Guides

Main tool chains for publishing FHIR IGs:

• The FHIR IG Publishing tool
• Simplifier

In addition, the following tools may be useful for IG authors while building IGs:

• Editing Profiles / extension definitions / logical models: Forge
• Editing Implementation Guide resources
• Editing Value Sets, Concept Maps & Code systems:
• Editing Example Scenarios:
• Editing Questionnaires:

Other resources have to be edited by hand.