Canonical Resource Management Infrastructure Implementation Guide
2.0.0-ballot - STU 2 - Ballot
Canonical Resource Management Infrastructure Implementation Guide
2.0.0-ballot - STU 2 - Ballot
This page is part of the Canonical Resource Management Infrastructure Implementation Guide (v2.0.0-ballot: STU 2 Ballot) based on FHIR (HL7® FHIR® Standard) R4. This version is a pre-release. The current official version is 1.0.0. For a full list of available versions, see the Directory of published versions
| Page standards status: Informative |
This page documents the use cases and conformance expectations of a terminology service to support authoring, distribution, and evaluation of FHIR-based knowledge artifacts as described in this implementation guide.
This implementation guide is not advocating for any particular central authority for terminology content, rather the intent is to propose a capability statement that enables publishers to build consistent and interoperable terminology services that support authoring, distribution, and implementation of FHIR-based knowledge artifacts.
This implementation guide is not prescriptive about authentication or authorization, but strongly recommends that these capabilities be addressed through standard mechanisms, as described in FHIR standard security mechanisms. In addition, though knowledge artifacts typically do not include patient-specific information, test data for knowledge artifacts can sometimes be derived from or based on real patient information. In these cases, care must be taken to ensure the data is scrubbed to remove any possibility of violating patient privacy or security.
Beyond the basic required use cases of searching, retrieving, and expanding value sets, applications that reference value sets that are defined in terms of code systems from different authorities and with different publishing timelines face common challenges related to stable expansion of those value sets. To address that general problem, this implementation guide proposes the concept of a manifest that provides information about the usage artifacts for development and release. From the perspective of a terminology service, manifests provide two main capabilities:
Note that during the authoring phase, as content is being developed, the value sets referenced by artifacts will in general change. However, once released, the set of dependencies must be stable. The focus of the capabilities supported by this service description is to ensure stable expansion of the value sets referenced by the artifacts throughout the content development and usage lifecycle.
As a manifest library, an artifact collection specifies the complete set of dependencies referenced by artifacts in the collection, recursively. In a release manifest, this information is represented using using relatedArtifact elements with a type of depends-on.
Some systems will not support the ability to version manifests, any changes needed would require a new manifest. (i.e. versioning of manifests is a MAY)
NOTE: If the version of an artifact is specified explicitly as part of the declaration in the artifact, the manifest approach can still be used to override that version using the force- version parameters (force-system-version, force-valueset-version, and force-canonical-version). Alternatively, particular versions can be checked (i.e. returning an error if particular versions are not used) using the check- version parameters (check-system-version, check-valueset-version, and check-canonical-version).
Artifact collections can specify expansion rules (i.e. manifest parameters) for value sets referenced by artifacts in the collection. This is done using the cqf-expansionParameters extension to reference a contained Parameters resource that conforms to the CRMIManifestParameters profile. The parameters in this Parameters resource provide default values for parameters to the $expand operation, consistent with the conformance requirements for the $expand operation supported by an artifact terminology service, including support for the following parameters:
activeOnlydefault-system-version (may still be seen as system-version for backwards-compatibility)default-valueset-vesrioncheck-system-versioncheck-valueset-versionforce-system-versionforce-valueset-versionincludeDraft (defined in CRMIValueSetExpand)lastActiveVersion (defined in CRMIValueSetExpand)NOTE: CRMIManifestParameters is a generalization of expansion parameters, and may also contain
default-canonical-version,check-canonical-versionandforce-canonical-versionparameters to identify pinned versions of canonical resources other than CodeSystems and ValueSets. See the Version Manifest discussion for more information.
Because this capability results in the potential for parameter values to be supplied in multiple places, the following rules apply:
default-valueset-version parameter is specified in the manifest parameters (and no version for the value set is specified in the artifact reference), the version has the same meaning as the valueSetVersion parameter to the $expand (in the case that value set is being expanded directly) or as the default-valueset-version parameter otherwisedefault-system-version parameter is specified in the manifest parameters (and no version for the code system is specified in the artifact reference), the version has the same meaning as the system-version parameter to the $expandNOTE: The term artifact collection can also be understood as a content Implementation Guide, in which case the ImplementationGuide resource serves as the container for the collection of artifacts; all the same discussions and use cases apply, in particular the ability to use the cqf-expansionParameters extension as described here. The CRMIImplementationGuide profile supports this use case.
For ImplementationGuide, this extension specifies expansion parameters to be used for all ValueSet expansions for ValueSets defined in the IG or referenced by artifacts defined in the IG.
Expansion parameters specified in the IG override expansion parameters specified in dependency IGs, and can be overridden by expansion parameters in downstream IGs.
When the cqf-expansionParameters extension is used, it is intended to be binding (i.e. expansion SHALL take the expansion parameters into account, according to the expansion rules discussed here.
NOTE: The previous version of this implementation guide used an "expansion" parameter to allow clients to request persisted expansions using the expansion identifier (one such system is VSAC). However, the "manifest" capability provided through FHIR terminology services replaces the need for the use of the expansion parameter. Some servers may use the manifest identifier as an expansion identifier to facilitate access to and use of persisted expansions.
Terminology services MAY act as a repository for content that is managed and created elsewhere (i.e. hosted content AKA a convenience copy), or they MAY provide features to author and manage content directly, or any combination. When hosting content that is managed externally, the service must ensure that the content of the resource is materially the same (i.e. the values for all elements are the same where those elements are specified in the Shareable and Publishable profiles) as the source of truth. In particular, for systems that provide both management and hosting of externally managed content, the status element for hosted content SHALL be the same as the status of the content in the source of truth.
SHALL Represent basic CodeSystem information, as specified by the ShareableCodeSystem profile, which includes url, version, name, status, experimental, publisher, description, caseSensitive, content, and concept.
For published CodeSystems, SHALL represent publishable CodeSystem information, as specified by the CRMIPublishableCodeSystem profile.
For hosted content, the data-absent-reason extension with a value of unknown MAY be used to satisfy required cardinality constraints of the Shareable and Publishable code system profiles when an element is not present in the source of truth for the content.
CodeSystem resources returned by the repository SHALL use the meta.profile element to indicate which profiles the CodeSystem resource conforms to.
SHALL support CodeSystem read by the server-defined id for the CodeSystem
SHALL support CodeSystem/$lookup
When determining the URI for a code system, the HL7 Universal Terminology Governance (UTG) site is the source of truth. If a code system is not identified there, submit a request with the HL7 Terminology Authority to identify an appropriate URL. For example, HCPCS Level II codes are not specified yet, discussion can be found here.
In accordance with the FHIR specification, CodeSystem resources, and references to code systems SHALL use the URI as specified by the HL7 terminology authority. In addition, version identifiers for code systems are specified according to the rules identified by the code system authority. For example, for SNOMED-CT, this means the version string is required to specify the edition and the version:
http://snomed.info/sct/731000124108/version/20150301
The edition identifier for the US Edition is 731000124108, and the version in the
above example is the March 2015 release, specified as YYYYMMDD, 20150301.
Note that when a code system authority has not established a versioning system, terminology servers may, as a practical matter, determine an appropriate versioning system to enable consistent use of content from that code system. However, in this case, the selected versioning scheme SHALL be brought to the HL7 Terminology Authority for consideration as the standard versioning scheme for that code system.
SHALL Represent computable ValueSet information, as specified by the CRMIComputableValueSet profile, which specifies the definition of a value set using established extensions, or with the compose element, including in particular the ability to use the inactive element of the include to indicate that a specific code is inactive in the code system but should still be included in the expansion.
For hosted content, the data-absent-reason extension with a value of unknown MAY be used to satisfy required cardinality constraints of the Shareable and Publishable value set profiles when an element is not present in the source of truth for the content.
ValueSet resources returned by the repository SHALL use the meta.profile element to indicate which profiles the ValueSet conforms to, Shareable, Publishable, Computable, or Expanded.
SHALL Represent expanded ValueSet information, as specified by the CRMIExpandedValueSet profile, which specifies the complete content of a value set using the expansion element, including inactive codes specified in the compose.
For published ValueSets, SHALL represent publishable ValueSet information, as specified by the CRMIPublishableValueSet profile.
SHALL support ValueSet read, by the server-defined id for the ValueSet
SHALL Represent basic artifact collection information, as specified by the CRMIManifestLibrary profile, which includes identifier, title, type, date, useContext, effectivePeriod, and terminology references
For published artifact collections, SHALL represent publishable artifact collection information as specified by the CRMIPublishableLibrary profile.
SHALL support Library read, by the server-defined id for the library
includeDraft parameter (defined in CRMIValueSetExpand)lastActiveVersion parameter (defined in CRMIValueSetExpand)default-valueset-version parameter is specified in the manifest parameters (and no version for the value set is specified in the artifact reference), the version has the same meaning as the valueSetVersion parameter to the $expand (in the case that value set is being expanded directly) or as the default-valueset-version parameter otherwisedefault-system-version parameter is specified in the manifest parameters (and no version for the code system is specified in the artifact reference), the version has the same meaning as the system-version parameter to the $expanddraft to active (using PUT)active status to retired (using PUT)url and version as another librarySHALL support the metadata?mode=terminology, returning a list of all supported code systems, whether they are explicitly made available as CodeSystem resources or not
Services MAY require authentication. If authentication is required, it SHALL be in the form of an authentication header (usually a bearer token) that the user can determine in advance and provide to their FHIR tooling in some configuration.
contains and exact modifierstextThe above capabilities are formally captured in the following capability statement:
CRMIArtifactTerminologyService
This is the computable representation of an example Chronic Liver Disease value set. It contains two concepts that are active (as of the 2019-09 release of the US Edition of SNOMED-CT) and one concept that was last active in the 2015-03 release).
The compose element of this value set is:
"compose": {
"include": [
{
"system": "http://snomed.info/sct",
"concept": [
{
"code": "1116000",
"display": "Chronic aggressive type B viral hepatitis (disorder)"
},
{
"code": "10295004",
"display": "Chronic viral hepatitis (disorder)"
}
]
},
{
"system": "http://snomed.info/sct",
"version": "http://snomed.info/sct/731000124108/version/20150301",
"concept": [
{
"code": "111370006",
"display": "Cirrhosis of liver not due to alcohol (disorder)"
}
]
}
]
}
Note specifically the use of the inactive element to indicate that the
value set definition contains inactive codes, and the use of separate
include elements, one for the codes that do not specify a code system version,
and one for the legacy code from version http://snomed.info/sct/731000124108/version/20150301.
Given the following $expand:
[base]/ValueSet/chronic-liver-disease-legacy-example/$expand
The expected result expansion is:
"expansion": {
"timestamp": "2021-02-05T08:57:00-06:00",
"contains": [
{
"system": "http://snomed.info/sct",
"code": "1116000",
"display": "Chronic aggressive type B viral hepatitis (disorder)"
},
{
"system": "http://snomed.info/sct",
"code": "10295004",
"display": "Chronic viral hepatitis (disorder)"
},
{
"system": "http://snomed.info/sct",
"inactive": true,
"code": "111370006",
"display": "Cirrhosis of liver not due to alcohol (disorder)"
}
]
}
Note the use of the inactive element to indicate the code 111370006 is inactive in the
current version of SNOMED (i.e. the version of SNOMED that was active when this
expansion was produced, and the use of the timestamp to ensure that date is known).
Given the following $expand:
[base]/ValueSet/chronic-liver-disease-legacy-example/$expand?activeOnly=true
The expected result expansion is:
"expansion": {
"timestamp": "2021-02-05T08:57:00-06:00",
"parameter": [
{
"name": "activeOnly",
"valueBoolean": true
}
],
"contains": [
{
"system": "http://snomed.info/sct",
"code": "1116000",
"display": "Chronic aggressive type B viral hepatitis (disorder)"
},
{
"system": "http://snomed.info/sct",
"code": "10295004",
"display": "Chronic viral hepatitis (disorder)"
}
]
}
The result of the activeOnly parameter is to exclude the inactive code, even
though it was explicitly included in the value set definition.
Given the following $expand:
[base]/ValueSet/chronic-liver-disease-legacy-example/$expand?valueSetVersion=2020-05&system-version=http://snomed.info/sct|http://snomed.info/sct/731000124108/version/20150301
The expected result expansion is:
"expansion": {
"timestamp": "2021-02-05T08:57:00-06:00",
"parameter": [
{
"name": "valueSetVersion",
"valueString": "2020-05"
},
{
"name": "system-version",
"valueUri": "http://snomed.info/sct|http://snomed.info/sct/731000124108/version/20190901"
}
],
"contains": [
{
"system": "http://snomed.info/sct",
"code": "1116000",
"display": "Chronic aggressive type B viral hepatitis (disorder)"
},
{
"system": "http://snomed.info/sct",
"code": "10295004",
"display": "Chronic viral hepatitis (disorder)"
},
{
"system": "http://snomed.info/sct",
"inactive": true,
"code": "111370006",
"display": "Cirrhosis of liver not due to alcohol (disorder)"
}
]
}
Note this expansion contains the same codes as the current example, but is explicitly
bound to the 2019-09 version of the US Edition of the SNOMED code system (http://snomed.info/sct/731000124108/version/20190901).
From the perspective of artifact development, artifact collections are used to represent collections of artifacts in 2 different ways:
Note that as the artifacts in the collection are developed, different aspects of the definition will be specified at different points of the process. For example, the initial definition will typically include a set of artifacts, as well as an initial set of proposed code system versions to be used. This provides for stable expansion of value sets while the artifacts are being developed. As development progresses, more and more aspects of the collection definition are finalized, resulting in more versions being pinned down. To illustrate these usages, we provide three artifact collection examples, one to illustrate the overall definition of a collection, one to illustrate the selection of code systems at the beginning of a development cycle, and one to illustrate a final release of a collection definition with artifact versions, value set versions, and code system versions completely specified.
The following example illustrates an overall collection that contains multiple version manifests and releases over time:
Note that as an organizer, this library just contains the collection-level information.
This example illustrates the use of a draft quality program description to specify the version of SNOMED to be used for valuesets used by artifacts in the quality program.
"contained": [
{
"resourceType": "Parameters",
"id": "exp-params",
"parameter": [
{
"name" : "system-version",
"valueUri" : "http://snomed.info/sct|http://snomed.info/sct/731000124108/version/20190901"
},
{
"name": "activeOnly",
"valueBoolean": true
},
{
"name": "includeDraft",
"valueBoolean": true
}
]
}
],
"extension": [
{
"url": "http://hl7.org/fhir/uv/crmi/StructureDefinition/crmi-expansionParameters",
"valueReference": {
"reference": "#exp-params"
}
}
],
This example indicates that unless specified explicitly by artifacts in the collection, the 2019-09-01 version of SNOMED SHALL be used when expanding value sets that reference SNOMED.
Note that the version of SNOMED in use is still listed as a dependency in the artifact collection to support providing a complete listing of dependencies in the version manifest. When this is done, the version provided in the expansion parameters SHALL take precedence (though the version manifest SHOULD be consistent with the expansion parameters).
"relatedArtifact": [
{
"type": "depends-on",
"resource": "http://snomed.info/sct|http://snomed.info/sct/731000124108/version/20190901",
"display": "SNOMED-CT US Edition, 2019-09-01"
}
]
The following example illustrates a collection that is an active instance of an artifact collection release used to provide stable extensions for the released artifacts in the collection.
Specifically, the collection includes a manifest parameters that specifies pinned versions of unversioned references used in the artifact collection, as well as expansion parameters to be used when expanding value sets used in the artifact collection:
...
{
"name": "system-version",
"valueCanonical": "http://snomed.info/sct|http://snomed.info/sct/731000124108/version/20190901"
},
...
In addition, the collection release specifies versions of code systems, value sets, and artifacts included in or referenced by artifacts in the release:
{
"type": "depends-on",
"resource": "http://snomed.info/sct|http://snomed.info/sct/731000124108/version/20190901",
"display": "SNOMED-CT US Edition, 2019-09-01"
},
{
"type": "depends-on",
"resource": "http://hl7.org/fhir/uv/crmi/ValueSet/chronic-liver-disease-legacy-example|2020-05",
"display": "Chronic Liver Disease, Legacy Example (2020-05)"
},
{
"type": "composed-of",
"resource": "http://hl7.org/fhir/uv/crmi/Measure/measure-exm124-FHIR|9.0.0",
"display": "Cervical Cancer Screening"
},
{
"type": "composed-of",
"resource": "http://hl7.org/fhir/uv/crmi/Measure/measure-exm125-FHIR",
"display": "Breast Cancer Screening"
},
{
"type": "composed-of",
"resource": "http://hl7.org/fhir/uv/crmi/Measure/measure-exm130-FHIR",
"display": "Colorectal Cancer Screening"
},
{
"type": "composed-of",
"resource": "http://hl7.org/fhir/uv/crmi/Measure/measure-exm146-FHIR",
"display": "Appropriate Testing for Children with Pharyngitis"
}
Given this use of an artifact collection, the manifest parameter can be used in the $expand operation to provide values for the relevant parameters:
[base]/ValueSet/chronic-liver-disease-legacy-example/$expand?manifest=http://hl7.org/fhir/uv/crmi/Library/ecqm-update-2020
This is effectively an alternative mechanism for expressing the same value set and code system version specific expansion above, and results in the same expansion, with the additional manifest parameter:
"expansion": {
"timestamp": "2021-02-05T08:57:00-06:00",
"parameter": [
{
"name": "valueSetVersion",
"valueString": "2020-05"
},
{
"name": "system-version",
"valueUri": "http://snomed.info/sct|http://snomed.info/sct/731000124108/version/20190901"
},
{
"name": "manifest",
"valueUri": "http://hl7.org/fhir/uv/crmi/Library/ecqm-update-2020"
}
],
"contains": [
{
"system": "http://snomed.info/sct",
"code": "1116000",
"display": "Chronic aggressive type B viral hepatitis (disorder)"
},
{
"system": "http://snomed.info/sct",
"code": "10295004",
"display": "Chronic viral hepatitis (disorder)"
},
{
"system": "http://snomed.info/sct",
"inactive": true,
"code": "111370006",
"display": "Cirrhosis of liver not due to alcohol (disorder)"
}
]
}
Similarly, when using a release for the manifest parameter:
[base]/ValueSet/chronic-liver-disease-legacy-example/$expand?manifest=http://hl7.org/fhir/uv/crmi/Library/ecqm-update-2020-05-07
This is effectively the same as providing the relevant system-version parameters to the value set expand, and results in the expansion with the appropriate code system versions:
"expansion": {
"identifier": "eCQM%20Update%202020-05-07",
"timestamp": "2021-02-05T08:57:00-06:00",
"parameter": [
{
"name": "valueSetVersion",
"valueString": "2020-05"
},
{
"name": "system-version",
"valueUri": "http://snomed.info/sct|http://snomed.info/sct/731000124108/version/20190901"
},
{
"name": "manifest",
"valueUri": "http://hl7.org/fhir/uv/crmi/Library/ecqm-update-2020-05-07"
}
],
"contains": [
{
"system": "http://snomed.info/sct",
"code": "1116000",
"display": "Chronic aggressive type B viral hepatitis (disorder)"
},
{
"system": "http://snomed.info/sct",
"code": "10295004",
"display": "Chronic viral hepatitis (disorder)"
},
{
"system": "http://snomed.info/sct",
"inactive": true,
"code": "111370006",
"display": "Cirrhosis of liver not due to alcohol (disorder)"
}
]
}
IG © 2022+ HL7 International / Clinical Decision Support. Package hl7.fhir.uv.crmi#2.0.0-ballot based on FHIR 4.0.1. Generated 2025-08-01
Links: Table of Contents |
QA Report
| Version History |
|
Propose a change