FHIR CI-Build

This is the Continuous Integration Build of FHIR (will be incorrect/inconsistent at times).
See the Directory of published versions icon

5.9 Resource ImplementationGuide - Content

FHIR Infrastructure icon Work GroupMaturity Level: 4 Trial UseSecurity Category: Anonymous Compartments: No defined compartments

A set of rules of how a particular interoperability or standards problem is solved - typically through the use of FHIR resources. This resource is used to gather all the parts of an implementation guide into a logical whole and to publish a computable definition of all the parts.

5.9.1 Scope and Usage

An implementation guide (IG) is a set of rules about how FHIR resources are used (or should be used) to solve a particular problem, with associated documentation to support and clarify the usage. Classically, FHIR implementation guides are published on the web after they are generated using the FHIR Implementation Guide Publisher icon.

The ImplementationGuide resource is a single resource that defines the logical content of the IG, along with the important entry pages into the publication, so that the logical package that the IG represents, so that the contents are computable.

In particular, validators are able to use the ImplementationGuide resource to validate content against the implementation guide as a whole. The significant conformance expectation introduced by the ImplementationGuide resource is the idea of Default Profiles. Implementations may conform to multiple implementation guides at once, but this requires that the implementation guides are compatible (see below).

5.9.2 Boundaries and Relationships

Implementation Guides contain two different types of resource references:

  • Contents: A set of logical statements which implementations must conform to. These are almost always conformance resources
  • Examples: Examples that illustrate the intent of the profiles defined in the implementation guide. These can be any kind of resource

An application's Capability Statement may identify one or more implementation guides that an application conforms to.

5.9.3 References to this Resource

5.9.4 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. ImplementationGuide TU DomainResource A set of rules about how FHIR is used
+ Warning: Name should be usable as an identifier for the module by machine processing applications such as code generation
+ Rule: If a resource has a fhirVersion, it must be one of the versions defined for the Implementation Guide

Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
Interfaces Implemented: CanonicalResource
... url ΣC 1..1 uri Canonical identifier for this implementation guide, represented as a URI (globally unique)
+ Warning: URL should not contain | or # - these characters make processing canonical references problematic
... identifier Σ 0..* Identifier Additional identifier for the implementation guide (business identifier)

... version Σ 0..1 string Business version of the implementation guide
.... versionAlgorithmString string
.... versionAlgorithmCoding Coding
... name ΣC 1..1 string Name for this implementation guide (computer friendly)
... title ΣT 0..1 string Name for this implementation guide (human friendly)
... status ?!Σ 1..1 code draft | active | retired | unknown
Binding: PublicationStatus (Required)
... experimental Σ 0..1 boolean For testing only - never for real usage
... date Σ 0..1 dateTime Date last changed
... publisher ΣT 0..1 string Name of the publisher/steward (organization or individual)
... contact Σ 0..* ContactDetail Contact details for the publisher

... description T 0..1 markdown Natural language description of the implementation guide
... useContext Σ 0..* UsageContext The context that the content is intended to support

... jurisdiction ΣXD 0..* CodeableConcept Intended jurisdiction for implementation guide (if applicable)
Binding: Jurisdiction ValueSet (Extensible)

... purpose T 0..1 markdown Why this implementation guide is defined
... copyright T 0..1 markdown Use and/or publishing restrictions
... copyrightLabel T 0..1 string Copyright holder and year(s)
... packageId Σ 1..1 id NPM Package name for IG
... license Σ 0..1 code SPDX license code for this IG (or not-open-source)
Binding: S P D X License (Required)
... fhirVersion ΣC 1..* code FHIR Version(s) this Implementation Guide targets
Binding: FHIRVersion (Required)

... dependsOn Σ 0..* BackboneElement Another Implementation guide this depends on

.... uri Σ 1..1 canonical(ImplementationGuide) Identity of the IG that this depends on
.... packageId Σ 0..1 id NPM Package name for IG this depends on
.... version Σ 0..1 string Version of the IG
.... reason 0..1 markdown Why dependency exists
... global Σ 0..* BackboneElement Profiles that apply globally

.... type Σ 1..1 code Type this profile applies to
Binding: Resource Types (Required)
.... profile Σ 1..1 canonical(StructureDefinition) Profile that all resources must conform to
... definition C 0..1 BackboneElement Information needed to build the IG
+ Rule: If a resource has a groupingId, it must refer to a grouping defined in the Implementation Guide
.... grouping C 0..* BackboneElement Grouping used to present related resources in the IG

..... name T 1..1 string Descriptive name for the package
..... description T 0..1 markdown Human readable text describing the package
.... resource C 0..* BackboneElement Resource in the implementation guide

..... reference 1..1 Reference(Any) Location of the resource
..... fhirVersion C 0..* code Versions this applies to (if different to IG)
Binding: FHIRVersion (Required)

..... name T 0..1 string Human readable name for the resource
..... description T 0..1 markdown Reason why included in guide
..... isExample 0..1 boolean Is this an example
..... profile 0..* canonical(StructureDefinition) Profile(s) this is an example of

..... groupingId C 0..1 id Grouping this is part of
.... page C 0..1 BackboneElement Page/Section in the Guide
+ Rule: Source must be absent if 'generated' is generated
..... source[x] TC 0..1 Source for page
...... sourceUrl url
...... sourceString string
...... sourceMarkdown markdown
..... name 1..1 url Name of the page when published
..... title T 1..1 string Short title shown for navigational assistance
..... generation C 1..1 code html | markdown | xml | generated
Binding: Guide Page Generation (Required)
..... page 0..* see page Nested Pages / Sections

.... parameter 0..* BackboneElement Defines how IG is built by tools

..... code 1..1 Coding Code that identifies parameter
Binding: Guide Parameter Code (Extensible)
..... value 1..1 string Value for named type
.... template 0..* BackboneElement A template for building resources

..... code 1..1 code Type of template specified
..... source 1..1 string The source location for the template
..... scope 0..1 string The scope in which the template applies
... manifest 0..1 BackboneElement Information about an assembled IG
.... rendering Σ 0..1 url Location of rendered implementation guide
.... resource Σ 1..* BackboneElement Resource in the implementation guide

..... reference Σ 1..1 Reference(Any) Location of the resource
..... isExample 0..1 boolean Is this an example
..... profile 0..* canonical(StructureDefinition) Profile(s) this is an example of

..... relativePath 0..1 url Relative path for page in IG
.... page 0..* BackboneElement HTML page within the parent IG

..... name 1..1 string HTML page name
..... title 0..1 string Title of the page, for references
..... anchor 0..* string Anchor available on the page

.... image 0..* string Image within the IG

.... other 0..* string Additional linkable file in IG


doco Documentation for this format icon

See the Extensions for this resource

 

Additional definitions: Master Definition XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) , the spreadsheet version & the dependency analysis

5.9.4.1 Terminology Bindings

Path ValueSet Type Documentation
ImplementationGuide.versionAlgorithm[x] VersionAlgorithm Extensible

Indicates the mechanism used to compare versions to determine which is more current.
ImplementationGuide.status PublicationStatus Required

The lifecycle status of an artifact.
ImplementationGuide.jurisdiction JurisdictionValueSet Extensible

This value set defines a base set of codes for country, country subdivision and region for indicating where a resource is intended to be used.

Note: The codes for countries and country subdivisions are taken from ISO 3166 icon while the codes for "supra-national" regions are from UN Standard country or area codes for statistical use (M49) icon.
ImplementationGuide.license SPDXLicense Required

The license that applies to an Implementation Guide (using an SPDX license Identifiers, or 'not-open-source'). The binding is required but new SPDX license Identifiers are allowed to be used (https://spdx.org/licenses/).
ImplementationGuide.fhirVersion FHIRVersion Required

All published FHIR Versions.
ImplementationGuide.global.type ResourceType Required

Concrete FHIR Resource Types
ImplementationGuide.definition.resource.fhirVersion FHIRVersion Required

All published FHIR Versions.
ImplementationGuide.definition.page.generation GuidePageGeneration Required

A code that indicates how the page is generated.
ImplementationGuide.definition.parameter.code GuideParameterCode Extensible

Codes used to define implementation guide parameters

5.9.4.2 Constraints

UniqueKeyLevelLocationDescriptionExpression
img cnl-0Warning (base)Name should be usable as an identifier for the module by machine processing applications such as code generationname.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')
img cnl-1Warning ImplementationGuide.urlURL should not contain | or # - these characters make processing canonical references problematicexists() implies matches('^[^|# ]+$')
img ig-1Rule ImplementationGuide.definitionIf a resource has a groupingId, it must refer to a grouping defined in the Implementation Guideresource.groupingId.all(%context.grouping.id contains $this)
img ig-2Rule (base)If a resource has a fhirVersion, it must be one of the versions defined for the Implementation Guidedefinition.resource.fhirVersion.all(%context.fhirVersion contains $this)
img ig-3Rule ImplementationGuide.definition.pageSource must be absent if 'generated' is generatedgeneration='generated' implies source.empty()

5.9.4.3 Distributing Implementation Guides

Implementation Guides are published through the FHIR Package distribution system. For further details, see the FHIR NPM Packages.

5.9.4.4 Authoring Implementation Guides

Implementation Guides can be produced using any tooling that produces a human readable output and a package that includes an ImplementationGuide along with all the supporting resources it refers to, and their dependencies. Note that dependencies included in other packages that the Implementation guide identifies as dependencies are not included in the package.

See Confluence icon for a list of tools that can assist with authoring implementation guides. HL7 publishes a Guidance Implementation Guide icon that provides specific guidance on best practices around IG creation as well as information about some of the tooling extensions and capabilities relevant to creation and publication of implementation guides. Note that this documentation mixes general documentation about the design of implementation guides with tooling specific advice based on one particular tool.

5.9.4.5 Roles of Implementation Guides

Implementation Guides are packages of both computer processible content (resources) and human readable documentation (html). The resources typically specify some combination of:

Note that any kinds of resources can be included; these are just the common uses.

In addition, in the human readable portions, implementation guides often:

  • Describe security arrangements in place for the relevent data exchanges, along with consent and access control requirements
  • Detail additional rules about the user of the narrative in the resources
  • Specify other conformance expectations that aren't testable directly
  • Outline the business arrangements and expectations under which the data is exchanged

5.9.4.6 Multi-Version Implementation Guides

Most implementation guides target a single version - that is, they describe how to use a particular version, and all the profiles, value sets and examples they contain etc. are valid for that particular version.

In other cases, however, implementation of an implementation guide is not confined to a single version. Typically, the requirement to support multiple versions arises as implementation matures and different implementation communities are stuck at different versions by regulation or market dynamics. Applications may be stuck at different versions of the specification. See Managing Multiple Versions for further information about cross-version support.

For this reason, implementation guides might describe how to use multiple different versions of FHIR for the same purpose. The different versions might have different profiles, extensions, and examples, while sharing common value set definitions, for example. For some reasons, profiles and examples could be common across all versions. And an implementation guide will generally have a lot of common narrative describing the problem, security approaches, and other deployment information irrespective of specific FHIR versions.

An implementation guide specifies which versions of FHIR it describes in the ImplementationGuide.fhirVersion property: 

  "fhirVersion" : ["4.0", "5.0"],

This specifies that the implementation guide applies to both Release 4 icon and Release 5 icon. Note that the patch version (".1" for Release 3) is omitted, since the patch releases never make changes that make any difference to Implementation Guides.

Note that it is possible to have an Implementation Guide that declares support for one version and imports an Implementation Guide that declares support for a different version. It is up to the importing IG ad/or the tooling that supports Implementation Guides to determine whether it's safe and/or appropriate to reference the different resources from the new IG, and what to make of this.

As yet, there is no experience with multi-version implementation guides and current publication tooling does not support creation of such IGs. As we work to evolve the tools to provide such support, additional guidance on how such guides should be created, what types of content can safely be shared across versions, and how such sharing should occur will be forthcoming.

 

5.9.4.7 Default Profiles

An implementation guide can define default profiles using ImplementationGuide.global- these are profiles that apply to any resource that does not otherwise have an explicit profile assigned by the implementation guide. Default profiles are always references to profiles (StructureDefinition resources) that are also contained in the resources. By defining default profiles, an implementation guide can save itself from exhaustively defining profiles on every resource type just to profile every reference to a particular resource type.

Note that a resource can conform to the default profile by conforming to any profile derived from it.

5.9.5 Search Parameters

Search parameters for this resource. See also the full list of search parameters for this resource, and check the Extensions registry for search parameters on extensions related to this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

Name Type Description Expression In Common
context token A use context assigned to the implementation guide (ImplementationGuide.useContext.value.ofType(CodeableConcept)) 30 Resources
context-quantity quantity A quantity- or range-valued use context assigned to the implementation guide (ImplementationGuide.useContext.value.ofType(Quantity)) | (ImplementationGuide.useContext.value.ofType(Range)) 30 Resources
context-type token A type of use context assigned to the implementation guide ImplementationGuide.useContext.code 30 Resources
context-type-quantity composite A use context type and quantity- or range-based value assigned to the implementation guide On ImplementationGuide.useContext:
  context-type: code
  context-quantity: value.ofType(Quantity) | value.ofType(Range)		 30 Resources
context-type-value composite A use context type and value assigned to the implementation guide On ImplementationGuide.useContext:
  context-type: code
  context: value.ofType(CodeableConcept)		 30 Resources
date date The implementation guide publication date ImplementationGuide.date 31 Resources
depends-on reference Identity of the IG that this depends on ImplementationGuide.dependsOn.uri
(ImplementationGuide)
description string The description of the implementation guide ImplementationGuide.description 29 Resources
experimental token For testing only - never for real usage ImplementationGuide.experimental
global reference Profile that all resources must conform to ImplementationGuide.global.profile
(StructureDefinition)
identifier N token External identifier for the implementation guide ImplementationGuide.identifier 35 Resources
jurisdiction token Intended jurisdiction for the implementation guide ImplementationGuide.jurisdiction 27 Resources
name string Computationally friendly name of the implementation guide ImplementationGuide.name 28 Resources
publisher string Name of the publisher of the implementation guide ImplementationGuide.publisher 31 Resources
resource reference Location of the resource ImplementationGuide.definition.resource.reference
(Any)
status token The current status of the implementation guide ImplementationGuide.status 35 Resources
title string The human-friendly name of the implementation guide ImplementationGuide.title 28 Resources
url uri The uri that identifies the implementation guide ImplementationGuide.url 34 Resources
version token The business version of the implementation guide ImplementationGuide.version 32 Resources