Canonical Resource Management Infrastructure Implementation Guide
1.0.0-ballot2 - Ballot
Canonical Resource Management Infrastructure Implementation Guide
1.0.0-ballot2 - Ballot
This page is part of the Canonical Resource Management Infrastructure Implementation Guide (v1.0.0-ballot2: STU1 Ballot 2) based on FHIR (HL7® FHIR® Standard) R4. . For a full list of available versions, see the Directory of published versions
This page documents the use cases and conformance expectations of an artifact repository service to support authoring, publishing, and distribution of FHIR-based knowledge artifacts including questionnaires, decision support rules, quality measures, guidelines, and reporting specifications, as well as their associated terminologies and data element descriptions.
This implementation guide is not advocating for any particular central authority for content repositories, rather the intent is to propose a capability statement that enables publishers to build consistent and interoperable repositories for sharing 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 to use cases for knowledge artifact management, this page defines three levels of artifact repository capabilities:
This section describes the general use case of knowledge artifact management as a special case of content management. Specifically, we apply semantic versioning and apply controls through the use of status, as described in the artifact lifecycle topic. The use cases for artifact management are then described in artifact operations.
Knowledge artifacts as represented within FHIR follow a general, high-level content development work flow, 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.
Knowledge artifacts represented as FHIR resources have multiple ways of identifying the artifact:
Knowledge artifacts SHALL provide and maintain a globally unique, version-independent identifier in the url element. When referencing knowledge artifacts, a reference may be version-independent by providing only the canonical URL, or the reference may be version-specific, using the | 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
As a best practice, content versions SHOULD follow semantic versioning. To summarize this scheme as it applies to knowledge artifacts, 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. Under this scheme, the first type of change is referred to as a major change, and will require incrementing of the major version number. The second type of change will be referred to as a minor change, and will only require incrementing of the minor version number. And finally, the third type of change will be referred to as a patch, and will only require incrementing the patch version number.
Version numbers for artifacts can then be represented as:
<major>.<minor>.<path>
For example:
1.0.0
Note that versioning content often involves pre-release content, and this scheme supports that through the use of labels such as SNAPSHOT. This is indicated with a - following the version number:
1.0.0-SNAPSHOT
Content MAY use additional labels to support pre-release content or other versioning and build metadata use cases.
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 here make use of these elements for knowledge artifacts.
To support content authoring, searching, publication, and distribution, the following general operations are defined:
An artifact repository SHALL support retrieval of an artifact by its server-specific id.
Because artifacts in FHIR share consistent metadata attributes, searching can be defined across all artifacts.
Artifact repositories SHALL support searching for artifacts by the following parameters:
Artifact repositories SHOULD support searching for artifacts by the following parameters:
Artifact repositories MAY support searching for artifacts by the following parameters:
The package operation supports the ability of a repository to package an artifact for a particular target environment, and with required components and dependencies included.
If the resulting bundle is paged using count or offset, it will be of type collection. In the special case where count = 0 it will be of type searchset.
The following parameters SHOULD be supported for packaging operations:
computable to include computable elements in packaged content, executable to include executable elements in packaged content, publishable to include publishable elements in packaged content.computable if they can be expanded based on these capabilities, and executable (expanded) otherwise| checkArtifactVersion: Edge Case: Specifies a version to use for an artifact. If the artifact is referenced with a different version, an error is returned instead of the package. The format is the same as a canonical URL: [system] | [version] - e.g. http://loinc.org | 2.56 |
| forceArtifactVersion: Edge Case: Specifies a version to use for an artifact. This parameter overrides any specified version of the artifact (and any it depends on). The format is the same as a canonical URL: [system] | [version] - e.g. http://loinc.org | 2.56. Note that this has obvious safety issues, in that it may result in a value set expansion giving a different list of codes that is both wrong and unsafe, and implementers should only use this capability reluctantly. It primarily exists to deal with situations where specifications have fallen into decay as time passes. If the value is override, the version used SHALL explicitly be represented in the expansion parameters |
depends-on related artifacts in the root artifact have the same meaning as specifying that artifact version in the artifactVersion parameter.The result of the packaging operation is a Bundle (or Bundles if there is a need to partition based on size) containing the artifact, tailored for content based on the requested capabilities, and any components/dependencies as specified in the parameters. This operation can also be
The requirements operation supports the ability of a repository to determine the effective requirements of an artifact, including:
The following parameters SHOULD be supported for the requirements operations:
| checkArtifactVersion: Edge Case: Specifies a version to use for an artifact. If the artifact is referenced with a different version, an error is returned instead of the requirements. The format is the same as a canonical URL: [system] | [version] - e.g. http://loinc.org | 2.56 |
| forceArtifactVersion: Edge Case: Specifies a version to use for an artifact. This parameter overrides any specified version of the artifact (and any it depends on). The format is the same as a canonical URL: [system] | [version] - e.g. http://loinc.org | 2.56. Note that this has obvious safety issues, in that it may result in a value set expansion giving a different list of codes that is both wrong and unsafe, and implementers should only use this capability reluctantly. It primarily exists to deal with situations where specifications have fallen into decay as time passes. If the value is override, the version used SHALL explicitly be represented in the expansion parameters |
depends-on related artifacts in the library have the same meaning as specifying that code system version in the system-version parameter.The result of the requirements operation is a module-definition Library that returns the computed effective requirements of the artifact.
The submit operation supports posting a new artifact in draft status. This operation is defined as a POST (or PUT if the server supports client-defined ids) of the artifact resource, but the status of the posted resource is required to be draft.
The revise operation supports updating an existing artifact in draft status. This operation is defined as a PUT of the artifact resource, but the status of both the existing and updated resources is required to be draft.
The withdraw operation supports deleting an existing artifact in draft status. This operation is defined as a DELETE of the artifact resource, but the status of the deleted resource is required to be draft.
The review operation supports applying a review to an existing artifact, regardless of status. The operation sets the date and lastReviewDate elements of the reviewed artifact, and is otherwise only allowed to add artifactComment elements to the artifact, and to add or update a reviewer.
The approve operation supports applying an approval to an existing artifact, regardless of status. The operation sets the date and approvalDate elements of the approved artifact, and is otherwise only allowed to add an artifactAssessment resource to the repository.
The following parameters SHOULD be supported for the operation:
| artifactAssessmentTarget: The version-specific canonical URL for the artifact being approved. The format is: [system] | [version] - e.g. http://loinc.org | 2.56 |
The publish operation supports posting a new artifact with active status. The operation is defined as a POST (or PUT if the server supports client-defined ids) of the artifact resource, but the status of the posted resource is required to be active.
The release operation supports updating the status of an existing draft artifact to active. The operation sets the date element of the resource and pins versions of all direct and transitive references. Child artifacts (i.e. artifacts that compose the existing artifact) are also Released, recursively.
The following parameters SHOULD be supported for the operation:
The draft operation supports the creation of a new draft version of an existing artifact in active status. This operation creates a new resource with the same contents as the existing artifact, but with a status of draft and a pre-release label of -draft appended to the version.
The following parameters SHOULD be supported for the draft operations:
The clone operation supports the creation of a new draft version of an existing artifact, regardless of status, with a new URL. This operation creates a new resource with the same contents as the existing artifact, but with a status of draft and not version, and the new URL.
The retire operation supports updating the status of an existing active artifact to retired. The operation sets the date element of the resource, but is otherwise not allowed to change any other elements of the artifact.
The archive operation supports removing an existing retired artifact from the repository. The operation is defined as a DELETE but the status of the deleted resource is required to be retired.
The ShareableArtifactRepository capability statement defines the minimum expectations for an artifact repository that provides basic access to shareable artifact content. It describes the minimum required functionality for sharing FHIR-based artifact content.
The CRMIShareableArtifactRepository capability statement captures these requirements formally, while the following sections provide a narrative description of them.
Note that the shareable artifact repository defined here supports only the knowledge artifacts that are the primary focus of this implementation guide:
Repository support for other types of artifacts SHALL follow the same pattern established for these artifacts.
For each type of knowledge artifact supported by a ShareableArtifactRepository:
SHALL Represent basic artifact information, as specified by the shareable profile for the artifact, which includes url, identifier, version, name, title, type, status, experimental, date, publisher, contact, description, useContext, and jurisdiction.
For computable artifacts, SHALL represent computable artifact information, as specified by the computable artifact profile.
For executable artifacts, SHALL represent executable artifact information, as specified by the executable artifact profile.
For published artifacts, SHALL represent publishable artifact information, as specified by the publishable artifact profile.
SHALL support artifact read by the server-defined id for the artifact
SHALL support artifact searches by:
The PublishableArtifactRepository capability statement expresses additional functionality that SHOULD be provided in support of providing published FHIR artifacts including additional searching and packaging capabilities.
The CRMIPublishableArtifactRepository capability statement captures these requirements formally, while the following sections provide a narrative description of them.
Note that the publishable artifact repository defined here supports only the knowledge artifacts that are the primary focus of this implementation guide:
Repository support for other types of artifacts SHALL follow the same pattern established for these artifacts.
For each type of knowledge artifact supported by a PublishableArtifactRepository:
The AuthoringArtifactRepository capability statement defines additional capabilities that are required to support content authoring workflows in a shared environment. For systems that do not exchange in progress content, or support external review/approval processes, these capabilities are not required to be exposed.
The CRMIAuthoringArtifactRepository capability statement captures these requirements formally, while the following sections provide a narrative description of them.
Note that the authoring artifact repository defined here supports only the knowledge artifacts that are the primary focus of this implementation guide:
Repository support for other types of artifacts SHALL follow the same pattern established for these artifacts.
For each type of artifact supported, an AuthoringMeasureRepository:
IG © 2022+ HL7 International / Clinical Decision Support. Package hl7.fhir.uv.crmi#1.0.0-ballot2 based on FHIR 4.0.1. Generated 2023-12-20
Links: Table of Contents |
QA Report
| Version History |
|
Propose a change