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 that 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. 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 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 (see FHIR Implementation Guide Publishing Requirements), 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), its scope, and its canonical URL
    • For HL7 guides, the root of the canonical URL will be http://hl7.org. For other guides, it may be http://fhir.org, http://ihe.org etc
  • Choose a template for your IG (see FHIR IG publisher templates)
  • Create an initial ImplementationGuide 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
  • Run a local build to check that all the content is all OK
    • commit to publish to the CI build site (if setup, so that everyone can see the current work)

• 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 Standard FHIR Publishing Layout 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 its time as it is drafted and then published in official consensus builds.

Publishing Implementation Guides

todo: further information about the publishing process. General guidelines:

• copy the generated content to your web server
• upload the registry.fhir.org.zip file to registry.fhir.org
• updated the fhir implementation guide registry see [[1]]

Kinds of content in a typical Implementation Guide

Implementation guides typically include the following kinds of content:

• Resources
  • Profiles and Extension definitions - defining the content models of the resources covered by the guides
  • Value Sets and Code Systems - supporting terminology definitions for the implementation guides
  • Capabilty Statements, along with Operation Definitions and Search Parameters - define how the FHIR API is used
  • Test Cases (Test Script) - a set of actual tests that implementations do or should pass
  • ExampleScenaro - formal definitions of storyboard for the IG (which may drive test scripts or other testing frameworks)
  • ConceptMap and StructureMap - maps & transforms from or to FHIR content described by the guide
  • Logical models - see documentation of Logical Models in Implementation Guides
  • Examples - any kind of resources that further illustrate the implementation guide

• Narrative:
  • Process information : version & license, publisher/owner, where to report issues / join in discussion
  • security information: how security works (for application solution type guides)
  • domain analysis/background information
  • UML diagrams, BPMN flow diagrams, other kinds of diagrams

Note that all these contents are optional, and which is appropriate depends on the actual content of the IG and the problem that is being solved. Authors should keep Best practice Guidelines for IGs in mind while developing their IGs

If you want an example of IG source, you can look in one of the following places:

• FHIR GitHub repository, in /guides/* - any directory ending in 2 - a variety of styles of implementation guide.
• Also, there's /tests/ig which is used for testing the tooling

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: Forge (limited)
• Editing Value Sets, Concept Maps & Code systems:
• Editing Example Scenarios:
• Editing Questionnaires:

Other resources have to be edited by hand.