Content Repository Management Infrastructure Implementation Guide, published by HL7 International / Clinical Decision Support. This guide is not an authorized publication; it is the continuous build for version 3.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/crmi-ig/ and changes regularly. See the Directory of published versions
| Page standards status: Trial-use |
To facilitate publishing and distribution of canonical resources and knowledge artifacts, this Implementation Guide provides guidance on how to package knowledge artifacts, either independently, or as part of a collection of related artifacts.
In general, artifacts such as libraries, measures, and test cases can be packaged as a Bundle
of type transaction. However, since large artifact packages may span multiple bundles, the type
collection MAY be used as well. In that case, Receiving systems SHOULD process collection bundles as a unit (i.e. as
a single transaction). The intent of splitting the bundles is to allow large packages to be processed,
but in the case that they are split, transactional considerations are the responsibility of the consumer.
An artifact bundle contains the artifact as the first entry in the bundle, and optionally the dependencies and associated artifacts as subsequent entries as follows:
Although the scope of the package is a single artifact, this same approach can be used for multiple artifacts by defining an asset-collection library as the main artifact.
Dependencies consist of any knowledge artifact referenced by the main artifact (or any dependency, recursively).
Note that packaging MAY be restricted in various ways, including:
Examples of artifact packages include:
NOTE: If an artifact package is large enough to require segmentation in multiple bundles, use of
transactionbundles may not be feasible.
NOTE: It is recommended that each resource in the transaction is a conditional create using the canonical URL and version as search parameters, e.g.:
"entry": [
{
"resource": {
"resourceType": "Library",
"url": "http://example.org/Library/SomeLibrary",
"version": "0.1.0",
// ...
},
"request" :{
"method": "POST",
"url": "Library",
"ifNoneExist": "url=http://example.org/Library/SomeLibrary&version=0.1.0"
}
}
]
Artifacts may also be packaged following the FHIR Package specification. This involves creating a NPM package (tarball archive with a package.json). The IGPublisher build tool creates a FHIR Package when building an implementation guide.
See also: FHIR Package Specification
Note that FHIR NPM packages are expected to have an ImplementationGuide resource with a packageId that matches the id of the package. This implementation guide defines a packageId search parameter for implementation guides. For example:
GET [base]/ImplementationGuide?packageId=hl7.fhir.uv.cql#1.0.0
To support packaging and distribution of the terminology required for a particular artifact, this implementation guide defines terminology profiles for the capability categories:
Whether to package and distribute Computable or Expanded value sets is a consideration of the target environment. If the environment is expected to have access to a fully-featured terminology server capable of expanding the required value sets, then packaging Computable value sets only can potentially save on bundle size. Conversely, if the target environment is not expected to have access to a terminology server (an occasionally connected environment for example), then packaging Expanded value sets only may be more appropriate.
In addition, the $package operation defines a terminologyCapabilities parameter to support more fine-grained control over how value sets are packaged for a particular environment.
Note that an Expanded value set is a point-in-time snapshot that becomes stale as the value set definition or the underlying code systems change. When expansions are included with production artifacts, additional requirements apply, as described in Production Expansions.
To support usage of a knowledge artifact, the artifact package contains the following general components:
In addition, packages may be built for specific environments with particular capabilities. At the highest level, packages may be requested to have the capability categories identified by this implementation guide (Shareable, Publishable, Computable, and Executable). More fine-grained control over capabilities may be provided by parameters to the packaging operation such as terminologyCapabilities.
The following are conformance requirements that apply to the FHIR Bundle when packaging an artifact using the bundling approach:
Conformance Requirement 4.1 (Artifact Packaging): ![]()
Conformance Requirement 4.2 (Intellectual Property Considerations): ![]()
Value set expansions that are included with an artifact (whether contained within the artifact, or included as a ValueSet resource in an artifact package or implementation guide) are produced for a particular environment using particular versions of the value set definition and of each underlying code system. For production artifacts, and particularly where the expansion includes codes from frequently updated external terminologies such as CPT, an evaluating system needs to be able to determine exactly what an included expansion represents, so that it can determine whether the expansion matches the terminology being used for evaluation.
The following table summarizes how each aspect of an included expansion is represented:
| Aspect | Representation |
|---|---|
| Value set canonical and definition version | ValueSet.url and ValueSet.version, plus a used-valueset expansion parameter for each value set included by the definition |
| Expansion date | ValueSet.expansion.timestamp |
| Expansion parameters | ValueSet.expansion.parameter, using the valueset-parameterSource extension to indicate the source of each parameter |
| Underlying code system versions | A used-codesystem expansion parameter for each code system, with a value of the form system\|version, as well as ValueSet.expansion.contains.version |
| Manifest or package version | A manifest expansion parameter providing a version-specific canonical reference to the manifest library or implementation guide under which the expansion was produced |
| Expansion identifier | ValueSet.expansion.identifier |
| Publisher and licensing | ValueSet.publisher and ValueSet.copyright |
Conformance Requirement 4.3 (Production Expansions): ![]()
url and versionexpansion.timestampexpansion.identifier, which SHALL uniquely identify the expansion (i.e. two expansions with different content SHALL NOT have the same identifier)expansion.parameterused-codesystem expansion parameter, with a value of the form system|version, for each code system from which codes in the expansion are drawnexpansion.contains.version for each code in the expansionused-valueset expansion parameter, with a version-specific canonical value, for each value set included by the value set definitionmanifest expansion parameter, with a version-specific canonical reference to the manifest library or implementation guide, when the expansion was produced in the context of a manifestpublisher and copyright, and the copyright SHOULD include the licensing notices required by each code system with licensing restrictions from which codes in the expansion are drawn (e.g. CPT, SNOMED CT)expansion.identifier or using an extension, to allow consumers to verify the integrity of the expansionConformance Requirement 4.4 (Evaluation with Production Expansions): ![]()
used-valueset and used-codesystem expansion parameters)used-codesystem version were provided as a check-system-version parameter (see ValueSet/$expand)In addition to code systems and value sets, computable artifacts may depend on terminology transformations, such as a ConceptMap used to translate clinical codes to administrative codes (e.g. SNOMED CT to CPT), or a mapping used to normalize local codes before evaluation. A mapping can materially change the output of an artifact even when the logic and value sets of the artifact are unchanged, so terminology transformations need to be identified and managed as dependencies in the same way as other terminology.
The following table summarizes how each aspect of a terminology transformation represented as a ConceptMap is identified:
| Aspect | Representation |
|---|---|
| ConceptMap canonical and version | ConceptMap.url and ConceptMap.version |
| Source and target code systems and versions | ConceptMap.group.source and ConceptMap.group.sourceVersion, ConceptMap.group.target and ConceptMap.group.targetVersion |
| Publisher and steward | ConceptMap.publisher (the organization responsible for the content and maintenance of the map), with contact, and optionally the author, editor, reviewer, and endorser extensions |
| Effective period | The resource-effectivePeriod extension |
| Relationship (equivalence) semantics | ConceptMap.group.element.target.equivalence |
| Mapping rule or context | ConceptMap.group.element.target.dependsOn, ConceptMap.group.element.target.product, ConceptMap.group.unmapped, and ConceptMap.purpose and ConceptMap.useContext for the map as a whole |
| Confidence or review status | For the map as a whole, the approvalDate, lastReviewDate, and reviewer extensions; for individual mappings, ConceptMap.group.element.target.comment |
| Licensing conditions | ConceptMap.copyright (and optionally the copyrightLabel extension) |
Conformance Requirement 4.5 (Terminology Transformation Dependencies): ![]()
relatedArtifact entry of type depends-on with the canonical of the ConceptMap (or other transformation artifact), in the same way as dependencies on libraries, code systems, and value setsdefault-canonical-version parameter, see Version Manifest)Conformance Requirement 4.6 (Production Concept Maps): ![]()
url and versiongroup.source, group.sourceVersion, group.target, and group.targetVersion for each grouppublishergroup.element.target.equivalence for each mapping (as required by the base ConceptMap resource)group.element.target.dependsOn and group.element.target.product to represent any mapping rule or context on which a mapping dependsapprovalDate, lastReviewDate, and reviewer extensions, and SHOULD indicate the confidence or review status of individual mappings, where applicable, using group.element.target.commentcopyright, and the copyright SHOULD include the licensing conditions for the map, as well as those required by each source or target code system with licensing restrictions (e.g. CPT, SNOMED CT)Mappings from clinical terminologies to administrative terminologies are inherently approximate, because administrative codes are assigned according to coding, billing, authorization, and reporting rules that depend on information not typically available to a mapping (such as payer policy, documentation requirements, and modifiers).
Caution: A CPT, HCPCS, or other administrative code produced by a terminology transformation is a candidate administrative concept. It SHOULD NOT be treated as an assigned or confirmed administrative code unless it has been confirmed through the applicable coding, billing, authorization, or quality-reporting process. Artifacts that use such mappings SHOULD make this distinction clear in their documentation and, where the result of the mapping is communicated, in their output.