FHIR:V1.0 FHIR Profiling Guidelines R4

Introduction

This page lays out the conventions for creating FHIR profiles and associated conformance resources within Nictiz. These guidelines are specifically aimed at FHIR R4; for the STU3 profiling work, a separate document exists.

This page is titled "profiling guidelines", but actually addresses all conformance resources (profiles, extensions, value sets, CapabilityStatements) and associated examples. We use these terms somewhat interchangable throughout this document; 'profile' can usually be read as 'the whole set of conformance resources'.

Open vs. Closed Modeling

×	Open	Closed
Pros	- Forward compatibility - Modelers don't have to think about what you shouldn't support, only what must be supported - Implementers can fit more data, even if it's not in specified explicitly bu the profile	- Implementers, don't have to support all elements that maybe, someday could be used, according to the model - Model becomes more specific - Model becomes smaller and more straightforward - More implementer feedback, about elements they want to support, but currently can't
Cons	- Implementers, have to support all optional elements that maybe, someday could be used, according to the model - Model becomes more vague, - Model becomes larger and less straightforward about what should actually be supported, and what can optionally be supported - Less implementer feedback: elements they want to send can be easier 'hacked' in a not yet explicitly specified element. Model won't be improved.	- More versions of models, after more elements have to be supported - No forward compatibility, only backwards - Implementers have to wait for a new version of the model, if they want to support elements, that are currently not in scope.

We have chosen for "open" modeling for the zibs, since they are very general and not meant for one specific use case. Excluding unspecified elements here is not an option, since we expect derived profiles for more specific use cases that may need those elements.

Versioning

Conformance resources are versioned on multiple levels:

• The version of the underlying data model.
• The FHIR Version (StructureDefinition.fhirVersion): this document is specifically aimed at FHIR R4, meaning this element will be fixed on 4.x.
• The version of the conformance resource (StructureDefinition.version): used to indicate the business version to the user, without strict specifications.
• The version of the package the conformance resources reside in: versioned according to SemVer 2.0.

For consistency and manageability reasons, the version of the conformance resources are inherited from the version number of the package. This means that all of the conformance resources get a new version number whenever a new package version is released, even if they aren't changed.

The life cycle of the underlying data model is reflected only indirectly in the versioning of conformance resources. The normal SemVer rules determine how a new release of the underlying data model should be handled; if it doesn't affect the conformance resources, nothing should be done, if it affects them in a backwards compatible way, a new patch release should be made, etc. If a new version of the underlying data model reflects a fundamental change, the choice can be made to create a completely new package.

Version updates of conformance resources normally do not affect the canonical URI. Any resource that references another resource normally does so without a version indicator (uri|version). Instead, this is handled at the package level; reference targets either reside within the same package or in a versioned package that has been added as a dependency.

Functional model as specification

Most, if not all, conformance resources are based on an underlying functional model. The functional model is the specification to which the conformance resources should adhere.

The basis for most other functional models is formed by the 'zibs' ('Zorginformatiebouwstenen'), in English also known as are Clinical Information Models (CIMs), Health and Care Information Models (HCIMs) or Clinical Building Blocks (CBB) -- we will use the Dutch term 'zib' for all profiling work as it has become a recognizable term over the past years. The zibs are defined by the program ‘Registratie aan de bron’ (Data capture at the point of care) and provide a foundation of use case neutral building blocks from which use cases can be built. The formal definition of the zibs can be found on the zibs wiki

Use cases or information standards use and refine those zibs that are relevant to the situation. The formal specification for these information standards can usually be found in Nictiz' instance of ART-DECOR.

Zibs, information standard specific profiles and uniprofiles

The profiles and other conformance resources align to this layering of information standards. We recognize three levels of profiles:

zib profiles

profiles that represent the zib as faithful as possible

uniprofiles

derived profiles from the zib profiles that form a 'union' of the uses case specific elements for all use cases that use a certain zib.

information standard specific profiles

derived profiles from the uniprofiles that further restrict or enhance the unionprofiles for a specific use case.

Identity of artifacts

Canonical URL, id, name and title

Conformance resources can have multiple types of identifying information, which are related at some level:

StructureDefinition.url

The canonical URL, which is the external identifier for conformance resources. All conformance resources SHALL have a canonical URL. This URL is preferably resolvable but does not have to be processable. Canonical URL's are about the identity of artifacts, not necessarily about retrieval location. Canonical URLs aren't meant to be human recognizable.

StructureDefintion.id

This should align with the latter part of the canonical URL.

StructureDefintion.name

A recognizable name that is still computer processable.

StructureDefintion.title

A recognizable title purely for human consumption.

URIs for the latter (for artifacts living in ART-DECOR) are described in ART-DECOR FHIR_URIs.

Profiles and extensions

• The id will be constructed in the following way:
  • For profiles:
    • zib profiles:zib-[English zib name]
    • uniprofiles:uni-[English zib name]
    • standard specific:[project prefix]-[concept name]
  • For extensions:
    • pertaining to 1 profile:[profile id]-[English concept name]
    • pertaining to multiple profiles, or not pertaining to specific profiles and generally applicable:
      • if the use context is a single resource:[resource]-[purpose]
      • otherwise:[purpose]
• The canonical URL will then be created as: http://nictiz.nl/fhir/4.0/StructureDefintion/[id]
• The name will be the .id capitalized, with hyphens removed.
• The title will generally be the .id with hyphens replaced by spaces.

Where:

• [project prefix] is preferably the same as its matching ART-DECOR project prefix
• [purpose] is generally a camelCased name starting with a lowercase letter

ValueSets

• For value sets as specified on ART-DECOR, the id will be:[value set OID]--[effective date as yyyymmddhhmmss]
• The canonical URL will then be created as: http://decor.nictiz.nl/fhir/4.0/ValueSet/[id]
• Both the name and title will be name of the value set (usually in Dutch).

ConceptMaps

• The id will be constructed as: [source ValueSet.name]-to-[target ValueSet.name]
• The canonical URL will then be: http://nictiz.nl/fhir/4.0/ConceptMap/[id]
• The name will be constructed as: [source ValueSet.name]_to_[target ValueSet.name]
• The title will be constructed as: [source ValueSet.name] to [target ValueSet.name]

Folder structure and file name

profiles

resources/[id].xml

extensions

resources/extension-[id].xml

valuesets

resources/terminology/[name]-[id].xml

conceptmaps

resources/terminology/conceptmap-[id].xml

examples

examples/[profile id]-[serial number, two digits].xml

Metadata of StructureDefinitions

• version: see #Versioning
• status: as applicable (normally draft or active)
• publisher: Nictiz
• contact:
  • name: Nictiz
  • telecom:
    • system: email
    • value: info@nictiz.nl
    • use: work
• description:
  • For profiles:
    • For zib profiles: the 'Concept' section from the zib.
    • For uniprofiles: TBD
    • For standard specific profiles: TBD
  • For extensions:
    • A description of what the extension is for.
• purpose:
  • For profiles:
    • For zib profiles: This [enter resource type] resource represents the Dutch [zib ('Zorginformatiebouwsteen', i.e. Health and Care Information Model) [English zib name] [version]([release])]([link to the English zib page on zibs.nl]).
    • For uniprofiles: A derived profile from [[id of zib profile]]([canonical of zib profile]) to provide a version better suited for implementation purposes. This profile augments the base profile with common elements found in the various use cases that have adopted the zib.
    • For standard specific profiles: A description with a reference to the base profile, with an explanation of why it has been added.
  • For extensions:
    • For extension representing a specific concept: This extension represents the [concept name] of ..., followed by a link to the functional description.
    • For other extensions this will likely be absent.
• copyright: CC0
• mapping: see #Associating_functional_definition_to_StructureDefinition)
• abstract: usually false, but may be set to true when this profile is to be used only as a base profile from which other profiles should be derived.
• comment on the root element: when special guidance on the use of this profile is needed, it will be placed here. For example: when this profile has a (non-trivial) relationship to other profiles, when a concept of the functional description is mapped over multiple elements, etc.

Associating functional definition to StructureDefinition

Any StructureDefinition that profiles a Resource does so because there is some kind of logical definition dictating how. Profiles SHALL have a traceable relationship with their functional counterpart(s).

The FHIR specification contains several solutions for this problem, ConceptMap (>=STU1), StructureMap (>=STU3), ElementDefinition.mapping. Neither of these solutions are mature and cover our use case.

• ConceptMap: works best for value sets and codes.
• StructureMap: overcomplicated and unclear how to apply and whether or not this has a future.
• ElementDefinition.mapping: is a free text mapping inside the profile. This means we cannot add mappings to profiles from third parties without updating their resource.

Current implementation

We use the mapping elements in profiles to map functional elements to resource elements. Functional elements are referenced based on their id in the functional model. The mapping shall resolve to a description of the functional model. For zibs, this should be the English page on zibs.nl.

When slicing, the mapping is made on the content of the slice, not the slice itself (see also #Placing-Info).

On the root element of the StructureDefinition, the mapping should thus be defined as:

<mapping>
    <identity value="zib-medicationagreement-v1.2-2020EN" />
    <uri value="https://zibs.nl/wiki/MedicationAgreement-v1.2(2020EN)" />
    <name value="zib MedicationAgreement-v1.2(2020EN)" />
</mapping>

A specific element can then be mapped using:

<element id="MedicationRequest.extension:usageDuration">
    <path value="MedicationRequest.extension" />
    <mapping>
        <identity value="zib-medicationagreement-v1.2-2020EN" />
        <map value="NL-CM:9.6.19936" />
        <comment value="PeriodOfUse" />
    </mapping>
</element>

Mapping semantic codes to profiles

Oftentimes a functional concept has an equivalent FHIR element, e.g. a 'comment' in the functional description maps in FHIR to the Resource.comment element. When this is not the case, a code (usually SNOMED or LOINC) is needed to add the proper definition to the FHIR resource, usually using the Resource.code element. For example, the root concept of an Observation is unknown unless it is defined by the .code element, and when components are used in an Observation, each Observation.component needs to be defined using an individual .code element.

These codes should be provided by the functional description (for zibs this is the DefinitionCode). These codes are profiled as required elements.

Miscellaneous

• We only profile elements, cardinalities and bindings that require profiling. We leave other elements, cardinalities and bindings as-is (see #Open_vs._Closed_Modeling)
• For elements that map to zibs:
  • The English name from the zib concept is placed on (in elements that refer to other zibs, the name is built up like <<ElementName::ReferenceZibName>>, but we only use the part before the double colons)
  • The zib concept description is placed on element.definition
  • The Dutch zib concept name is placed on element.alias
  • Note: as a rule of thumb, info is placed 'as close as possible' to the elements that actually represent the data. For example: when slicing, the texts are placed on the slice content, not the slice itself. Similarly, in concept containers like Observation.component, this info is placed on the .valueXXX elements. This is also true for the zib mappings.
• Slices get a lowerCamelCased name based on the zib element name.
• New elements defined through extensions get a lowerCamelCased name based on the zib element name.
• When adding invariants we use "zib-[zib-name]-[number]" as a key. Example: zib-alert-1
• For FHIR base resource elements with datatype code and binding required it may be that the functional description uses other/additional codes to specialize the FHIR codes. To conform to FHIR and the functional description:
  • The ValueSet from the functional description will be bound extensible using the code-specification extension. The extension slice is named after the full English name of the value set according to the functional description.
  • Mapping to the concepts of the functional description is applied both to FHIR element and the extension.
  • The mapping will be documented in a ConceptMap, which will be linked using the extension permitted-value-conceptmap extension.
• Inline examples in profiles are added (only) when the usage of an element in the profile is not trivial.

Constraining references

Concepts in a functional description oftentimes refer to each other; e.g. most clinical concepts will refer to the concept of a Patient. In FHIR these connections are realized using the reference datatype, which allow to specify the target (base resource of profile) as well. For example, a profile representing the zib Problem could set the target of the .subject element to the profile representing the zib Patient.

However, setting the target explicitly means a restriction of the allowed targets, which runs counter to the principles of open world modelling. On the other hand, specifying a dedicated profile provides useful guidance on how to handle this profile. To address both concerns, only the targets that are defined explicitly in the functional model are constrained, while other targets are left alone. For example, the Condition resource allows both Patient and Group as target in the .subject element. When profiling the zib Problem, the Patient target will be restricted to the profile representing the zib Patient, but the Group target is left as-is.

Data type mapping table

DECOR defines a set of data types. In most cases, the mapping to FHIR is straightforward, though there are a number of cases which are not as clear-cut. When defining extensions, or specifying the datatype of an Observation or Questionnaire.item in FHIR, a mapping to the relevant FHIR datatype needs to be done. The table below shows a mapping for datatypes in zibs versus those in profiles.

zib	ART-DECOR	FHIR	Remarks
INT	count	Count or integer	Count in FHIR is derived from Quantity, this is appropriate for observations, such a a count of red blood cells in a specimen. Count in FHIR is a Quantity with system="http://unitsofmeasure.org" and code="1" (for units). If this is not appropriate, use integer.
BL	boolean	boolean
ED	blob	base64Binary
CD	code	CodeableConcept or coding or code	In general, CodeableConcept will be the right choice. See Using Codes in Resources for details.
ANY	complex	BackboneElement	'complex' is data which is not further defined in DECOR, and thus cannot be translated.
-	currency	Money	Does not have a zib counterpart currenty. Theoretically this could be MO
-	date	date	Does not have a zib counterpart currently. Closest counterpart could be TS
TS	datetime	dateTime
-	decimal	decimal	Does not have a zib counterpart currently. Theoeratically this could be REAL
-	duration	Duration	Does not have a zib counterpart currently. Closest counterpart could be PQ
II	identifier	Identifier
CO	ordinal	CodeableConcept or coding or code	See Using Codes in Resources for details.
ST	string	string
-	ratio	Ratio	Does not have a zib counterpart currently. Closest counterpart could be RTO
-	text	string	Does not have a zib counterpart currently.
PQ	quantity	Quantity