Canonical Resource Management Infrastructure Implementation Guide
1.0.0 - STU1
Canonical Resource Management Infrastructure Implementation Guide
1.0.0 - STU1
This page is part of the Canonical Resource Management Infrastructure Implementation Guide (v1.0.0: STU1) based on FHIR (HL7® FHIR® Standard) R4. This is the current published version. For a full list of available versions, see the Directory of published versions
This topic discusses the use of terminology within artifacts and the challenges associated with achieving stable and predictable behavior of artifacts in the presence of external publication cycles.
The use of standardized terminologies in canonical resources (including profile and extension definitions, as well as knowledge artifacts such as questionnaires, measures, and decision support rules) is key to enabling interoperable semantics, allowing authors and consumers of these artifacts to share a common understanding. In particular, the use of ValueSets as a means for describing shared understanding of a clinical concept or set of concepts is ubiquitous in healthcare knowledge artifacts. However, the number of standardized terminologies, as well as the differing publication cycles and versioning strategies of each present significant challenges for both authors and implementers.
This section provides a brief introduction to the key aspects of terminology usage in knowledge artifacts, specifically FHIR-based knowledge artifacts, and then describes these challenges, and proposes a solution in the form of a version manifest.
Standardized terminologies are used throughout FHIR to represent coded values in FHIR resources, such as a Patient’s gender, the status and type of an Encounter, the code of a Condition or Procedure, or the code and result of an Observation. In all these cases, terminologies are used to represent the allowable values for these coded elements.
Within FHIR, terminologies are represented using the CodeSystem resource, which represents a single system of coded concepts. The CodeSystem resource is not intended for distribution, rather it is a description of the code system and its properties. CodeSystem resources may contain content, but not necessarily, and may even have partial content, depending on the code system and use case being represented.
Code systems may be enumerated, meaning they simply list the concepts that are part of the code system, or they may have a formal grammar that describes rules for valid concepts in the code system, or they may have both, i.e. some enumerated concepts, as well as rules for additional concepts.
A key aspect of a CodeSystem is that can be validated, i.e. it is always possible to tell, given a specific code, whether the code is a member of that system. Note that it may require a terminology server to be able to answer that question.
In addition, CodeSystems may have associated properties that define additional information for each concept in the CodeSystem, as well as relationships between concepts.
A ValueSet represents a collection of codes from one or more code systems. ValueSets are used throughout FHIR for various purposes including binding, i.e. a description of the allowable values for a codeable element.
ValueSet resources can have a definition and/or an expansion. The definition of a ValueSet is the instructions for how to build the contents of the value set (i.e. membership criteria), whereas the expansion of a ValueSet is an explicit listing of the members of the value set.
The definition of a ValueSet is represented in the compose element, while the expansion is represented in the expansion element.
Value set definitions can be intensional, where the membership of codes in the value set is defined in terms of expressive criteria:
73211009 | Diabetes mellitus (disorder) | and all child codes, recursivelyOr they can be extensional, where the definition is simply an enumeration of codes:
73211009 | Diabetes mellitus (disorder) |46635009 | Diabetes mellitus type 1 (disorder) |31321000119102 | Diabetes mellitus type 1 without retinopathy (disorder) |Note that whether a value set is defined intensionally or extensionally, a terminology server that understands the code systems involved in the ValueSet is required to calculate a proper expansion, not only because intensional criteria must be evaluated according to the rules and properties of the code system, but because even extensional value sets must be expanded with consideration for whether the codes are active in the version of the code system being used to perform the expansion.
For a complete discussion of terminology usage in FHIR and value set expansion, refer to the Terminology module in the FHIR specification.
Because value set definitions can refer to code systems generally, rather than to a specific version of a code system, as new code system versions are published, the expansion of a value set changes over time. Unless the version of the code system to be used is specifically identified as part of the expansion request, terminology servers will typically use the most recent version available version of the code system:
When value sets are used in conformance resources and knowledge artifacts, this means that depending on when and where a given artifact is used, expansions of value sets may be different, resulting in different behaviors. For example, if a quality measure is using a ValueSet to identify conditions of interest, whether or not a particular code is present in the expansion can mean the difference between a particular case being in or out of the numerator of the measure.
In addition, because artifacts are often used for many years after they were originally released, this problem grows worse over time, as depicted in the following diagram:
In this example, consider the development of a quality measure (as depicted by the box labelled ‘Measure’ in draft status). The measure refers to a specific value set of SNOMED-CT codes. At the time the measure is being authored (January 2021), the September 2020 version of SNOMED-CT is the latest available version (20200901). When the measure evaluated at this time, the expansion of the value set using the September 2020 version of SNOMED-CT would be, as depicted by the dotted line.
By the time the measure is released in May of 2021 (as depicted by the box labelled ‘Measure’ in active status), a new version of SNOMED-CT has been published, the March 2021 version, so evaluating the measure at this point would use an expansion of the value set with the March 2021 version of SNOMED.
When the measure is actually used in implementation, in the reporting year 2022, yet more versions of SNOMED-CT are published, resulting in even more potential for different expansions, and therefore different results for the evaluation of the same measure, even on the same input data.
To make matters worse, a new version of the measure is started in January of 2022, which at the time would use the September 2021 version of SNOMED, and by the time that new version is released, SNOMED will have released the March version.
Even in this simplified example, we have multiple versions of a measure using the same version of a value set and potentially producing different results depending on when the measure is evaluated.
In addition, this challenge exists for any artifact that makes use of value sets in FHIR, including profiles, extensions, questionnaires, decision support rules, measures, and others. The following sections consider proposed solutions to this problem, and recommends the solution provided by this implementation guide, a version manifest.
The first option we consider is to specify the code system version as part of the ValueSet definition. That way implementations will always get the same expansion because the code system version is explicit.
However, this option is contrary to one of the primary motivating factors for defining expression-based (i.e. intensional) value sets, that when new codes are added to a code system that meet the intent of the value set, they will be automatically included when the value set is expanded with that new version of the code system. Consider the intensional value set above for Diabetes; as new versions of SNOMED are published that include new children of the Diabetes mellitus code, those codes are automatically included.
In addition, using this option would result in a significant amount of value set maintenance. Every value set that referenced SNOMED, for example, would have to be versioned every time a new version of SNOMED was released.
This option would also mean that artifacts that made use of the value set would have to be updated to reference the new version of the value set, further compounding the amount of maintenance effort involved, as well as limiting the resuability of the resulting value sets.
The second option we consider is to specify the code system and value set versions as part of the artifact definition. For example, when authoring a quality measure that refers to the Diabetes value set above, refer to it by version specifically, and include information about the code system version that should be used to perform the expansion.
However, this option again creates a significant maintenance burden because it requires artifact authors to version their artifacts, even though nothing about the definition really changed.
The third option, and the one recommended by this implementation guide, is to separate the version information from both the artifact and the value set, and provide it as part of a version manifest, as depicted in the following diagram:
This approach means that the version information can be supplied as part of the release packaging for the artifact without needing to change either the value sets being used, or the artifacts being implemented.
In addition, it allows the same artifacts and value sets to be included in different artifact packages, and means that the version can be used to only reflect real change in the artifacts, rather than having to increment version information just to support terminology versioning.
A version manifest as defined by this implementation guide is an asset collection library (i.e. an instance of a Library resource with a type of asset-collection), and conforming to the CRMIManifestLibrary profile. A version manifest may contain any number of depends-on relatedArtifact entries to specify the version for any references to canonical resources within the artifacts of the release.
In addition, the version manifest profile allows for specifying the expansion parameters, i.e. values for the parameters that should be provided to the $expand operation whenever an expansion request is made.
Version manifests typically correspond to program-level artifacts such as “eCQM Annual Update - Eligible Hospitals”. A version manifest may have any number of composed-of relatedArtifact entries to specify the component artifacts that make up a release.
And to support artifacts that make use of Clinical Quality Language, a version manifest may also include a cqlOptions extension that allows various CQL options to be provided as part of the manifest.
To make use of a version manifest, whenever a version-independent canonical reference from an artifact needs to be resolved, first check the version manifest to determine whether the canonical has a version-binding in the manifest. If it does not, proceed as normal. If it does, use the canonical from the version-binding in order to resolve the reference.
There are two potential implementation strategies considered here:
manifest parameter to an operation that involves artifact evaluationX-Manifest header that allows the version manifest binding behavior to be described independent of the specific operation being performedThe first approach to implementation involves defining a manifest parameter on operations that involve artifact evaluation. This is the approach taken for the ValueSet/$expand operation defined in this implementation guide, and provides a way to describe the expected behavior as part of the definition of the operation. See the ValueSet/$expand operation definition for more details.
The second approach to implementation involves specifying an X-Manifest header that can be included in any server request and provides a way to specify what version manifest should be used for any artifact evaluation performed as part of fulfilling that request.
This approach has several advantages for implementation:
In this approach, the custom header X-Manifest is used to specify a version-specific canonical reference to the version manifest to be used:
POST [base]/Library/$evaluate
Content-Type: application/fhir+?
X-Manifest: http://example.org/fhir/Library/example-manifest
[body]
When performing the operation, whenever a canonical reference is resolved, if the reference is version-independent, then the version manifest is used to look up the canonical reference by url, and if a version binding is present in the manifest for that artifact, that is the reference used to resolve the resource.
For example, given the following reference to a ValueSet:
{
"resourceType": "Measure",
...
relatedArtifact: [
{
"type": "depends-on",
"display": "Value set Mammography",
"http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.108.12.1018"
}
]
}
And the following example manifest:
{
"resourceType": "Library",
"url": "http://example.org/fhir/Library/example-manifest",
...,
"relatedArtifact": [
{
"type": "depends-on",
"display": "Value set Mammography",
"http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.108.12.1018|20200505"
}
]
}
Resolving the canonical reference http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.108.12.1018 in the context of a request with the X-Manifest header above, will look up the example-manifest, search for a version-specific reference to that URL, and return the version-specific reference for resolution.
The result is that even though the artifact refers to a value set by a version-independent reference, it can be predictably bound to the specific version of the value set required for the release.
In addition, if the operation specifically involves value set expansion, the expansionParameters extension of the manifest can be used to provide values for the parameters to the expand (such as activeOnly and system-version).
And finally, if the operation specifically involves CQL evaluation, the cqlOptions extension of the manifest can be used to provide options to the CQL evaluation environment.
IG © 2022+ HL7 International / Clinical Decision Support. Package hl7.fhir.uv.crmi#1.0.0 based on FHIR 4.0.1. Generated 2024-05-31
Links: Table of Contents |
QA Report
| Version History |
|
Propose a change