Guidance for FHIR IG Creation
0.1.0 - CI Build

Guidance for FHIR IG Creation, published by HL7 International - FHIR Management Group. This is not an authorized publication; it is the continuous build for version 0.1.0). This version is based on the current content of https://github.com/FHIR/ig-guidance/ and changes regularly. See the Directory of published versions

Reading Implemenation Guides

Different implementation guides will have different settings used in their rendering. However, most implementation guides published using the HL7 IG templates will have a common set of behavior. This page provides an overview of the elements found in most implementation guides.

General appearance

These characteristics apply to most/all pages within the IG

Color scheme

The top and bottom of all HL7 IGs have color schemes that are specific to product family:

  • FHIR IGs use a red background
  • CDA IGs use a green background
  • V2 IGs use a blue background
  • Non-family-specific IGs use a grey background
  • Non-HL7 IGs use a purple background by default, though this can be overridden by organization-specific templates

Header

Structure Definitions

Model 'views'

A structure definition is made up of a collection of ElementDefinitions that describe the individual data elements that make up the model. When an implementation guide displays those elements, there are often different subsets of the elements that are of interest to the reader. For this reason, implementation guides offer up different 'views' of the model, each of which exposes different subsets of elements. This view-based approach is used for both the table views and the data dictionaries.

There are up to four different types of table view, though not all will appear in every implementation guide:

  • Differential - used to indicate what is 'different' between the parent model for the structure definition and the current model. In general, only those properties of the element that have changed will be shown, though some properties are always displayed to provide context. Element properties that are unchanged from the parent model are partially opaque, looking greyish. Element properties that have been removed from the parent model are rendered with strikethrough. This view shows "what has this profile done?" - it shows the content of the profile, but not necessarily everything that needs to be implemented or that is possible to share.
  • Snapshot - shows the complete set of data elements allowed within the profile. This is the result of applying all of the changes from the 'differential' to the base model. This view is the largest, as it includes everything that can be represented within the model by a conformant system. It is useful to understand the full context of what's possible, and is often the appropriate view to look at when seeking possible targets when mapping. Note that the snapshot only drills down into data types when the model imposes additional constraints on those types. This means that to see all data elements, the reader must click through the data types to see what those types contain. A full exapansion view that drills down into all data types is not possible because, with extensions, data types recurse. (Even if icons were used to denote recursion, the view would be too overwhelming to be useful for most models.)
  • Must Support - This is a trimmed-down version of the snapshot that only includes those data elements that are marked as mustSupport - i.e. those where the implementation guide requires specific application behavior related to the capture, storage, rendering, transmission, and/or other uses of the element. This view provides a quick scan of some of the most important elements, but is generally less useful than the 'Key elements' view.
  • Key Elements - This view includes a subset of the elements from the snapshot, including only those elements that need to be considered in some way as part of the implementation process. The elements that qualify as key elements are determined by the following process:
    a) Construct an initial list of elements meeting one of the following criteria:
    • The root element for the model
    • All elements that are marked as mustSupport
    • All elements that are listed in the differential - if the profile says something about them, they're presumed to be important)
    • All ancestor elements of those listed above. E.g. if an element is not mustSupport but contains descendants that are mustSupport, it will be considered a 'key element', even though support for it is optional because there are implementation considerations if the system chooses to support it.

    b) If any of those initial elements have unselected children, those children will be included if:
    • They are mandatory (minimum cardinality != 0) - important for senders, as they're responsible for including the element in instances
    • Their maximum cardinality has been constrained from the default cardinality for the resource or data type - may constrain what data the sender can transmit
    • They are implicated in a constraint that imposes rules on when they must be present or absent
    • They are slices of an element - slices impose constraints on certain uses of that element
    • The element is a modifier element - receivers must check for the presence of such elements with unexpected/supported values, as they may make processing of sibling elements unsafe

    c) Recurse step (b) for any newly included elements

    The result is a list of all elements that are most likely to be relevant to implementation. For included elements, the property values highlight any changes from the underlying value for the resource or data type.

Table Views

Table views provide a grid-like view of a structure definition, with a hierarchical view of the model supplemented by metadata describing the elements within the model. There can be multiple tables (typically in tabs) showing different subsets of elements (see Model Views above). Each of the views shows the resource, data type, extension definition or logical model with the following columns:

Column Content
Name This column starts with icon that denotes the underlying type of the element. The icons are described below. Following the icon is the name of the element in the resource/data type/logical model described by the row. If the element is an extension slice, the name of the extension slice will be displayed instead of the element name (which is always 'extension' or 'modifierExtension' and is implied by the icon). For other slices, this column will include both the name of the element and the name of the slice. Clicking on the name will jump to the data dictionary page for the element, which provides more detailed information, including full definitions and other guidance.
Flags A set of information about the element that impacts how implementers handle them. The flags are described below. Hovering over a flag will provide a description of its meaning.
Card. Cardinality: the lower and upper bounds on how many times this element is allowed to appear within the containing model or element. In some views, cardinality may be greyed out, indicating that they are unchanged from the reference model for that view.
Type The type (or types) of the element (hyperlinked to the definition of the type). These might be base data types or profiles of data types. If the type is one that references other models, the allowed target models that can be referenced will be listed in () brackets after the type name. As with cardinality, some views may also show changes from the reference model fro the view. In addition, within profiles, some types might be marked with the S mustSupport indicator (see the legend below).
Description & Constraints A short description of the element (from ElementDefinition.short) as well as certain constraints or other key information, including the vocabulary binding, fixed values or patterns, information about slicing behavior, the URL value for extensions, etc. In some views, content may be greyed out, indicating that they are unchanged from the reference model for that view. Full details about the element can be found on the corresponding data dictionary page.

Here's an example:

Name Flags Card. Type Description & Constraints
. . Resource Name Base Type Definition
. . . nameA Σ 1..1 TypeA description of content
. . . nameB[x] ?! Σ 0..1 description
SHALL at least have a value
. . . . nameBType1 0..1 Type1
. . . . nameBType2 I 0..1 type2
. . . nameC 1..* BackboneElement Definition
. . . . nameD 1..1 TypeD Relevant Records

Key to Type Icons

  • .: The base element for the model (parent resource, data type or logical model)
  • .: An element that is part of the model and has child elements within it defined as part of the same model
  • .: An element which can have one of several different types
  • .: An element of a data type which describes an element that has a value attribute/property. These are also known as primitive types. All primitive type names start with a lower case letter
  • .: An element of a data type which describes an element that has other elements. These are known as complex types. All complex type names defined in this specification start with an uppwer case letter
  • .: An element that contains a reference to another resource (see references)
  • .: This element has the same content as another element defined within this resource or profile
  • .: Introduction of a set of slices (see Slicing)
  • .: A complex extension - one with nested extensions (see Extensibility)
  • .: An extension that has a value and no nested extensions (see Extensibility)
  • .: A complex modifier extension - one with nested extensions (see Extensibility)
  • .: A modifier extension that has a value and no nested extensions (see Extensibility)
  • .: The root of a logical profile

Key to Flags

The data type for a particular element is typically expressed as the name of the specified type with a hyperlink to its definition. However, there are two exceptions:

  • If the element supports multiple types (name ends with [x]), then the type will be a list of data type options, each separated by "|"
  • If one of the types is Reference or canonical, the data type might be followed by a list of allowed targets the reference is allowed to be. These might be resource names, data type names, or profile URLs, depending on the context. As well, the following symbols may appear that represent expectations of where the referenced resource is located:
    • b: Resource must appear within the same Bundle;
    • c: Resource must be sent as a contained resource;
    • r: Resource is a non-contained reference - i.e. to a resource within the same Bundle or to an external resource

In profiles, references to types may be profiled - i.e. Instances of the element must comply with a specified profile or one of a list of profiles. The canonical URLs of any applicable profiles are listed inside {}.

Where an element can have a choice of data types, or is a Reference these are represented by showing the common type (Reference or Type), and then showing the applicable data type names or resource types in a stereotype, separated by the | character. Type is not formally otherwise defined by this specification, but is a super type of all the data types.

Data Dictionaries

Data dictionaries provide a list of model elements with full details about each element. There can be multiple data dictionary lists (typically in tabs) showing different subsets of elements (see Model Views above). Each of the views shows the only the elements that fall within the scope of that view. For some views, the information will also convey changes between the current model and the reference model for that particular view. For example, unchanged properties will be shown in grey, new properties in black and removed properties with strike-through.

TODO - list all of the types of information that can appear on the data dictionary page.