FHIR Profiling Guidelines for FHIR R4

Introduction

FHIR requires profiling. To do profiling in a comparable way we need conventions. This page lays out these conventions.

The created profiles are generally based on the Health and Care Information models (HCIM) defined by the program ‘Registratie aan de bron’ (Data capture at the point of Care) for the Netherlands. In the Netherlands, these models are more commonly known by the name zorginformatiebouwstenen or ZIB's. In this text, we make use of the HCIM abbreviation. The section Associating functional definition to StructureDefinition provides more information regarding these information models.

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:
  - HCIM profiles:zib-[English HCIM name]
  - uniprofiles:uni-[English HCIM 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]

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.

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="hcim-medicationagreement-v1.2-2020EN" />
    <uri value="https://zibs.nl/wiki/MedicationAgreement-v1.2(2020EN)" />
    <name value="HCIM 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="hcim-medicationagreement-v1.2-2020EN" />
        <map value="NL-CM:9.6.19936" />
        <comment value="PeriodOfUse" />
    </mapping>
</element>

Practical guidelines

Folder structure and file names

(Also see #Canonical URL, id, name and title):

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

Meta data 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 HCIM.
  - 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.

Mapping 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.

Slicing

Binding HCIM defined ValueSets

the ValueSet can be obtained in FHIR 3.0 format from ART-DECOR (see #File_names for file naming conventions)
the reference URL can be obtained from the <<ValueSet.url>> element in this file
we use binding strength "extensible".
the <<binding.description>> value is set to <<ValueSet.name>>

Binding of HCIM BasicElements to profiles

The BasicElements were made explicit in HCIM Release 2017 and have been declared applicable to 2015 and 2016 in the zibs.nl wiki.

Initially, the profiles did not dedicate much attention to the BsasicElements as there was no clarity around how to interpret them. That clarity has since been added but there is still room for interpretation:

For some elements it's clear, e.g. the IdentificationNumber will always go to .identifier, and for other elements it is not, e.g. InformationSource. What would be the InformationSource for the resource Patient? When would a ContactPerson be a Subject in the current profiles, instance had of a Patient?)

The table outlines which mappings are clear and which are yet to be determined. As of the Spring release 2019 of MedMij, all BasicElement mappings have applied for as far as possible:

BasicElement	Profiel element	Remark
NL-CM:0.0.1 HCIMRoot	-	not possible
NL-CM:0.0.6 IdentificationNumber	.identifier	Overlaps sometimes with existing mapping such as HealthProfessionalIdentificationNumber or PatientIdentificationNumber. Unclear what to do with sub parts of an HCIM such as LabroatoryTest and Specimen. Presumably best to map to Observation.identifier and Specimen.identifier
NL-CM:0.0.2 InformationSource	.asserter	Mapped only when clinically relevant, e.g. AllergyIntolerance.asserter, Condition.asserter. What HCIM is this really applicable to?
NL-CM:0.0.3 PatientAsInformationSource::Patient	Patient
NL-CM:0.0.4 HealthProfessional	Practitioner \| PractitionerRole
NL-CM:0.0.5 RelatedPersonAsInformationSource::ContactPerson	RelatedPerson
NL-CM:0.0.7 Author	.author \| .performer
NL-CM:0.0.8 PatientAsAuthor::Patient	Patient
NL-CM:0.0.9 HealthProfessionalAsAuthor::HealthProfessional	Practitioner \| PractitionerRole
NL-CM:0.0.10 RelatedPersonAsAuthor::ContactPerson	RelatedPerson
NL-CM:0.0.11 Subject	.subject \| .patient	A RelatedPerson is never a Subject of care except possibly for a family anamnesis. Is it clinically relevant and/or reasonable to assume RelatedPerson as possible subject regardless?
NL-CM:0.0.12 Patient	Patient
NL-CM:0.0.13 RelatedPersonAsSubject::ContactPerson	RelatedPerson
NL-CM:0.0.14 DateTime	.effective \| .onset	Is this clinically relevant time to be assumed only on clinical HCIMs? So not on e.g. Patient, Practitioner, Organization?

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 Health and Care Information Models (HCIM):
- We copy the name from the HCIM element into the profile element.short (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 HCIM concept description is placed in the profile element.definition
- The HCIM Dutch concept name is placed in the profile element.alias
- Note: as a rule of thumb, we place this info '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 HCIM mappings.
- Implementation guidance, such as mapping clarification and usage, of HCIM concepts that are mapped to multiple elements is given on the root of the resource. The nl-core-address profile provides a good example.
Slices get an UpperCamelCased name based on the HCIM element name.
New elements defined through extensions get a lowerCamelCased name based on the HCIM element name.
When adding invariants we use "hcim-[hcim-name]-[number]" as a key. Example: hcim-alert-1
FHIR URI Strategy (draft document with potentially good info)
For FHIR base resource elements with datatype code and binding required it may be that the HCIM has other/additional codes to specialize the FHIR codes. To conform to FHIR and the HCIM:
- We will document the mapping in a ConceptMap, which will be linked from the element .mapping comment.
- We will use the extension http://nictiz.nl/fhir/StructureDefinition/code-specification:
  - The extension is of datatype CodeableConcept, which also supports text as a fallback. It is bound with strength "extensible" on the HCIM derived ValueSet in the profile where it is applied.
  - The extension slice is named after the full English name of the code list according to the HCIM.
  - Mapping from the HCIM concepts is applied to the .valueCodeableConcept.mapping in the extension (in addition to the .mapping in the FHIR element).

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 HCIMs, 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.

Constraining references

HCIMs might have have connections to other HCIMs. Example: a MedicationAgreement might have a Prescriber relationship defined using a HealthProfessional which is mapped to a FHIR MedicationRequest.requester as Reference(Practitioner). The FHIR MedicationRequest however, defines more types: Reference(Practitioner | PractitionerRole | Organization | Patient | RelatedPerson | Device). The closed world model would mandate that the profile only marks Practitioner for use. The open world model would mandate that the profile describes that for a HealthProfessional you need the Practitioner without omitting the other choices.

For general purpose profiles, suitable for further constraining we use open world profiling meaning that we do not constrain the choices of references into just the types that the HCIM requires. We only constrain the generic resource reference to the generic profile(s) for that resource. For Practitioner this would be the nl-core-practitioner. If deemed relevant a second layer of derived profile(s) could be created to tailor the generic profile for a specific use case using closed world modeling.

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 HCIMs versus those in profiles.

HCIM	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 HCIM counterpart currenty. Theoretically this could be MO
-	date	date	Does not have a HCIM counterpart currently. Closest counterpart could be TS
TS	datetime	dateTime
-	decimal	decimal	Does not have a HCIM counterpart currently. Theoeratically this could be REAL
-	duration	Duration	Does not have a HCIM 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 HCIM counterpart currently. Closest counterpart could be RTO
-	text	string	Does not have a HCIM counterpart currently.
PQ	quantity	Quantity