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 section describes the use case of knowledge artifact management as a special case of content management. Specifically, we apply semantic versioning as described in the artifact lifecycle topic to support consistent change management, and describe conformance expectations for knowledge artifacts. The use cases for artifact management are then described in artifact operations.
The above diagram depicts the high-level phases of content development as:
The authoring phase is supported by the Shareable and Computable profiles defined in this implementation guide. See the Profiles page for a complete description of these capability categories and profiles.
See Artifact Conventions for artifact authoring conventions.
Knowledge artifacts as represented within FHIR follow a general, high-level content development workflow, as represented by the possible values of the status element of the artifact:
In addition, the experimental element may be used to indicate that the artifact is intended for testing/experimental usage only and should not be used in production settings.
Note that the status element is a general indication of the maturity of the content of the artifact, independent of any versioning, stability, or accessibility claims.
For any knowledge artifact, this implementation guide requires that:
Conformance Requirement 3.1 (Artifact Status): 
active artifact SHALL NOT transition back to draft. A new version of the artifact is required.retired artifact SHALL NOT transition back to active or draft. A new version of the artifact is required.If an invalid state transition occurs accidentally, the artifacts SHOULD be updated to the correct status and downstream systems SHOULD be notified as soon as possible.
Knowledge artifacts represented as FHIR resources have multiple ways of identifying the artifact:
Conformance Requirement 3.2 (Artifact Identity):
| notation to indicate the version of the artifact to be referenced:http://example.org/fhir/Library/ExampleLibrary // A version-independent reference to the ExampleLibrary published at example.org/fhir
http://example.org/fhir/Library/ExampleLibrary|1.0.0 // A version-specific reference to version 1.0.0 of the library
Note that this implementation guide defines profiles for several resources that are not strictly canonical resources (because they do not have a url element) but that can be used as knowledge artifacts:
When a resource is being used as a non-canonical artifact, the artifact-url and artifact-version extensions are used to provide a canonical url and version for the resource:
{
"resourceType": "Group",
"id": "example-non-canonical-artifact",
"extension": [{
"url": "http://hl7.org/fhir/StructureDefinition/artifact-url",
"valueUri": "http://example.org/fhir/Group/example-non-canonical-artifact"
}, {
"url": "http://hl7.org/fhir/StructureDefinition/artifact-version",
"valueString": "1.0.0"
}],
...
}
This allows a "canonical"-like reference to be constructed, following the same rules as a canonical reference to support both version-independent, and version-specific references:
http://example.org/fhir/Group/example-non-canonical-artifact // Version-independent reference
http://example.org/fhir/Group/example-non-canonical-artifact|1.0.0 // Version-specific reference
Note that because Group is not a canonical resource, these references cannot appear in a canonical-valued element. Instead, we use the artifact-uriReference extension to construct a reference:
{
"resourceType": "PlanDefinition",
...
"subjectReference": {
"extension": [{
"url": "http://hl7.org/fhir/StructureDefinition/artifact-uriReference",
"valueUri": "http://example.org/fhir/Group/example-non-canonical-artifact|1.0.0"
}]
},
...
}
This pattern can be used wherever there is a Reference- or canonical-valued element to refer to a non-canonical artifact. The profiles in this implementation guide make use of this extension to provide this support.
In addition, there are several domain-level resources that are used in a definitional way as part of knowledge artifacts by referring to profiles of these artifacts:
This IG recommends Semantic Versioning be used to version artifacts to help track and manage dependencies. As with FHIR, this IG allows for an exception to stock semantic versioning in that there is no expectation of ordering among labels. See FHIR Releases and Versioning.
Conformance Requirement 3.3 (Artifact Versioning):
<major>.<minor>.<patch>[-<label>]There are three main types of changes that can be made to an artifact:
By exposing version numbers that identify all three types of changes, artifacts can be versioned in a way that makes clear when a change will impact usage, versus when a change can potentially be safely incorporated as an update. The first type of change is referred to as a major change, and requires incrementing the major version number. The second type of change is referred to as a minor change, and requires incrementing the minor version number. And finally, the third type of change is referred to as a patch, and requires incrementing the patch version number. Version numbers for knowledge artifacts can then be represented as:
<major>.<minor>.<patch>
To summarize, breaking changes or major substantive new capabilities (such as materially changing whether a given recommendation will be applicable to a subject) require a major version number increment; non-breaking changes or minor new capabilities (such as refining the content of a questionnaire or adding stratifiers to a quality measure) require a minor version number increment; while non-substantive changes (such as fixing spelling mistakes and other minor technical corrections) require only a patch version number increment. Incrementing a version number resets version numbers to the right. E.g., When 1.3.5 contains a major change, it becomes 2.0.0, not 2.3.5. The scheme is for the benefit of consumers and so should be understood from that perspective.
Examples of labels in versions include:
1.0.0-cibuild - To indicate that the content is part of a continuous integration build and changes frequently1.0.0-draft - To indicate that the content is part of a draft release1.0.0-ballot - To indicate that the content is part of a ballotIn addition to the use of semantic versioning, this IG adds support for specifying an artifact version policy that applies to artifacts to allow consumers to understand what types of changes are indicated by version increments. This IG defines two version policies:
Conformance Requirement 3.4 (Artifact Versioning Policy):
metadata:
date element SHALL be updatedstrict:
In addition to identity, lifecycle, and versioning, knowledge artifacts typically have additional metadata such as descriptive content, documentation, justification, and source. This is especially true of published knowledge artifacts, which make this type of information available to enable consumers to find, understand, and ultimately implement the content. In FHIR, knowledge artifacts generally follow the Metadata Resource pattern. The capabilities described in the artifact repository service make use of these elements for knowledge artifacts.
Because artifacts are often authored, published, and consumed as a collection of artifacts (either as a published implementation guide, or as an artifact package such as a quality measure or set of measures), the version of an artifact is often established at the collection level and applied consistently to all the artifacts included in the package. In this case, the same considerations apply to establishing the version number, but because that version number is applied to all the artifacts in a package, it can be the case that an artifact has a new version, but does not actually have changes as indicated by its version number.
For example, if a new version of a computable guideline is published as a content implementation guide, but one of the value sets defined in the implementation guide has not changed, the value set may still be assigned the new version number of the content implementation guide as a whole, even though the content of that value set has not changed.
In addition, to ensure stable resolution of dependencies of an artifact throughout its lifecycle (including stable value set expansion), a version manifest should be used to allow resolution of unversioned canonical references in the artifact and its dependencies. See the Version Manifest discussion for more information on how the Manifest Library profile supports stable resolution of dependencies.
A collection of artifacts is represented using a CRMIManifestLibrary. The components of the collection are identified with relatedArtifact entries of type composed-of.
The dependencies of a collection can be stated explicitly using relatedArtifact entries of type depends-on, but because dependencies can always be inferred from the components, this listing is typically calculated. The $data-requirements operation can be used to calculate the dependencies of an artifact.
Conformance Requirement 3.5 (Artifact Collection Versioning):
The package source of an artifact is the package context in which it is authored, tested, and evaluated. This is typically specified by the implementation guide or package in which the artifact is published and distributed, and corresponds to the package id and base canonical url for the implementation guide. For example:
"packageId": "hl7.fhir.uv.crmi"
"canonical": "http://hl7.org/fhir/uv/crmi"
For knowledge artifacts that are authored and published as part of a FHIR Implementation Guide (i.e. a content IG), the package of the artifact is implied by the base canonical of the artifact URL. However, the package source of an artifact can be overridden using the cqf-scope extension.
The package source is important for determining the manifest (which dictates the expansion parameters used to resolve unversioned references). The manifest for a given package source is either the implementation guide (if the package source corresponds directly to an implementation guide), or the manifest library associated with the artifact collection identified by the packageId and url.
Conformance Requirement 3.6 (Artifact Package Source):
A Manifest Library can optionally provide information about how to determine where content can be accessed, based on the canonical URL for the content. Several of the operations defined in this implementation guide support providing this endpoint configuration information as a parameter to the operation, as described in the Artifact Endpoint Configurable operation profile, but this information can also be provided as part of a Manifest Library using the crmi-endpointConfiguration extension:
{
"resourceType": "Parameters",
"id" : "endpoints",
"parameter" : [{
"name": "artifactEndpointConfiguration",
"part": [{
"name" : "artifactRoute",
"valueUri" : "http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.1167|20220820"
}, {
"name" : "endpointUri",
"valueUri" : "https://example.org/fhir/"
}]
}, {
"name": "artifactEndpointConfiguration",
"part": [{
"name" : "artifactRoute",
"valueUri" : "http://cts.nlm.nih.gov/fhir/"
}, {
"name" : "endpointUri",
"valueUri" : "https://uat-cts.nlm.nih.gov/fhir/"
}]
}, {
"name": "artifactEndpointConfiguration",
"part": [{
"name" : "artifactRoute",
"valueUri" : "http://terminology.hl7.org/"
}, {
"name" : "endpointUri",
"valueUri" : "https://tx.fhir.org/r4/"
}]
}, {
"name": "artifactEndpointConfiguration",
"part": [{
"name" : "artifactRoute",
"valueUri" : "http://hl7.org/fhir/"
}, {
"name" : "endpointUri",
"valueUri" : "https://tx.fhir.org/r4/"
}]
}]
}
This endpoints Parameters resource is contained in the manifest library, and referenced by the crmi-endpointConfiguration extension:
{
"url" : "http://hl7.org/fhir/uv/crmi/StructureDefinition/crmi-endpointConfiguration",
"valueReference" : {
"reference" : "#endpoints"
}
}
A component artifact is an artifact that is designated specifically as part of a collection, whereas a dependency is an artifact that is referenced by another artifact. The distinction is drawn to ensure that dependencies can always be calculated by tracing artifact dependencies, whereas components always need to be specified (i.e. they are the designated components of the collection).
In addition, artifacts can be owned meaning that the lifecycle of the owned artifact is entirely controlled by the containing artifact, as opposed to the artifact having its own lifecycle. This is typically done for a collection of artifacts, but can also be done with specific elements (for example the primary measure library of a measure can be an owned artifact).
Within an artifact collection, the isOwned extension is used on the relatedArtifact entries of type composed-of specifying the components to designate whether a component is owned (i.e. managed entirely as part of the collection). A given artifact may only be owned by a single parent artifact.
The publishing phase is supported by the Publishable profiles defined in this implementation guide. See the Profiles page for a complete description of the Publishable capability category and profiles.
In addition, the $package and $data-requirements operations are concerned with tracing dependencies and constructing packages for the distribution of content.
See the Publishing topic for more information on publishing considerations.
The distribution phase is supported in two main ways:
The intent of this implementation guide is to ensure that both of these approaches are supported and that that support is provided in a way that is consistent with the existing FHIR Publishing ecosystem as well as FHIR API capabilities.
See the Distribution topic for more information on distribution considerations.
Note that artifacts can be authored, packaged, and distributed either individually, or as collections of artifacts.
Specifically, this IG defines capabilities for artifact repositories that support the content development lifecycle, with the goal of enabling a knowledge artifact ecosystem; in the same way that value sets are currently available via an ecosystem of terminology servers, artifacts should be readily available through an ecosystem of artifact repositories.
This IG is not prescriptive about whether content is distributed via IG packages or artifact repositories; both approaches are important and facilitate different use cases. This IG is focused on supporting both in consistent ways to ensure that however content is distributed, it can be reliably used by artifact consumers.
The implementation (or run-time) phase is supported by the Executable profiles defined in this implementation guide. See the Profiles page for a complete description of the Executable capability category and profiles.
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