Canonical Resource Management Infrastructure Implementation Guide
1.0.0-snapshot - Snapshot International flag

This page is part of the Canonical Resource Management Infrastructure Implementation Guide (v1.0.0-snapshot: STU1 Draft) based on FHIR (HL7® FHIR® Standard) R4. . For a full list of available versions, see the Directory of published versions

Profiles

For definitional artifacts, this implementation guide defines categories of profiles to represent knowledge capabilities for shareable, computable, publishable, and executable knowledge artifacts. These categories are proposed as a way to help facilitate management of expectations in the content development lifecycle, as well as address common challenges that have been encountered in the development of knowledge artifacts across the quality improvement spectrum, including guideline development, public health reporting specifications, clinical decision support rules, and quality measures. The expectation is that these same challenges will arise in any knowledge artifact development effort, and that the profiles and solutions proposed here will be useful in addressing those challenges.

Most knowledge artifacts are typically at least shareable, and where appropriate for the target environment, artifacts SHOULD declare the capabilities they support using the cqf-knowledgeCapability extension, as well as the knowledge representation level of the artifact using the cqf-knowledgeRepresentationLevel extension, as defined in the shareable profiles.

  • Shareable: Shareable profiles set the minimum expectations for including an artifact in a repository or implementation guide, including the URL, version, name, and publisher.
  • Computable: Computable profiles deal with authoring and design-time considerations, describing the minimum expectations for exchanging a machine-readable representation of an artifact. At a minimum, a computable artifact is one that does not have only human-readable content.
  • Publishable: Publishable profiles describe the expectations for publication and distribution of an artifact, typically as part of an artifact repository.
  • Executable: Executable profiles deal with run-time behavior and implementation considerations. For example, an executable library may contain compiled content that can be directly executed by an engine. At a minimum, an executable artifact is guaranteed to have all the elements required to support at least one operation appropriate to the type of artifact.

These capabilities are introduced to support separation of concerns along the spectrum from authoring to distribution to consumption, as illustrated by the following diagram:

knowledge-capabilities.png

A given artifact may provide all knowledge capabilities (Shareable, Computable, Publishable, and Executable), or it may be focused on a particular capability. For example, a ValueSet may be only Shareable and Expanded because it is intended for use in environments without access to a terminology service capable of expanding the Computable definition of the value set.

The profile categories are expressed as independent profiles to support separation of concerns. For example, a contained ValueSet included in a Questionnaire may not meet the Shareable profile (because it doesn’t have a stand-alone life-cycle) but it may still meet Computable expectations.

Profiles along the various axes may have different names appropriate to what capabilities are being provided. For example, ValueSet uses ExpandedValueSet, rather than ExecutableValueSet, to make clear what run-time capability is being provided by the profile.

Note that explicit profiles for capabilities are only defined when there are specific elements of the artifact involved in supporting that capability. For example, there is no executable ActivityDefinition profile, but that doesn’t mean that ActivityDefinition artifacts cannot be executable, only that there are no additional conformance expectations for executable ActivityDefinitions specified by this implementation guide.

Shareable

For knowledge artifacts, a shareable artifact defines the minimum expectations for knowledge artifact resources to be shared between authoring, publishing, and implementation systems. This pattern is intended to apply to Canonical Resources such as ValueSet, CodeSystem, StructureDefinition, Library, and so on. The pattern is defined to ensure that an artifact has enough metadata to make sharing it through a public repository reliable. The following table provides guidance for which elements should be present in a Shareable resource profile:

Element Guidance
url SHALL be provided because it provides the globally unique identity for the artifact
version SHALL be provided because it ensures version tracking is possible for the artifact
versionAlgorithm SHOULD be provided to ensure systems understand how to interpret the version element of the artifact
name SHOULD be provided to ensure systems can reliably make use of code-generation and other system-level processing for the artifact
title SHALL be provided to ensure systems can provide a user-friendly identifier for the artifact
status SHALL be provided to ensure systems can track the life-cycle of the artifact
experimental SHOULD be provided to ensure systems can differentiate production from experimental content
publisher SHOULD be provided to ensure consumers can identify the publisher (i.e. steward) of the artifact
description SHALL be provided to ensure systems can provide a meaningful human-readable description of the artifact
knowledgeRepresentationLevel SHOULD be provided to allow systems to understand the levels of representation of content provided by the artifact

Publishable

For knowledge artifacts, a publishable artifact defines the expectations for publication and distribution of an artifact, typically as part of an artifact repository. The Publishable pattern is defined to ensure that artifacts have enough metadata to understand when, where, and why a particular artifact would be used, as well as who contributed to it, who reviewed or endorsed it, and what evidence supports its use. The pattern is about ensuring artifacts can establish trust and credibility, as well as carry enough metadata to be discoverable in a public repository or artifact catalog. All “publishable” artifacts are also “shareable”. This pattern is intended to apply to Canonical Resources such as ValueSet, CodeSystem, StructureDefinition, Library, and so on. The following table provides guidance for which elements should be present in a Publishable resource profile:

Element Guidance
identifier MAY be provided to allow for additional identifiers beyond the URL (e.g. the OID)
date SHALL be provided to ensure systems have a mechanism to detect changes that may not be tracked by the version
contact SHOULD be provided to allow consumers to understand how to contact the publisher (i.e. steward) of the artifact
useContext SHOULD be provided to allow systems to categorize by and consumers to understand the appropriate context of use for the artifact
jurisdiction DEPRECATED, artifacts SHOULD use a useContext with a code of jurisdiction to provide this information for the artifact
purpose SHOULD be provided to allow consumers to understand why an artifact was created and the intended purpose of use
copyright SHOULD be provided to inform consumers about use and/or publishing restrictions
copyrightLabel SHOULD be provided to allow systems to display and consumers to understand copyright information
approvalDate SHOULD be provided to inform consumers about the primary approval date of the artifact
lastReviewDate SHOULD be provided to inform consumers when the artifact content was last reviewed
effectivePeriod SHOULD be provided to inform consumers what timeframe the artifact is intended to be used
topic DEPRECATED, artifact SHOULD use a useContext instead
author SHOULD be provided to inform consumers what authors contributed to the artifact
editor SHOULD be provided to inform consumers what editors were involved in the artifact
reviewer SHOULD be provided to inform consumers what individuals or organizations were involved in the review of the artifact
endorser SHOULD be provided to inform consumers what individuals or organizations have endorsed the artifact
relatedArtifact SHOULD be provided to support additional documentation, citations, etc. for the artifact

Computable

For knowledge artifacts a computable artifact identifies the aspects of the artifact that are primarily focused on authoring or design-time/compile-time considerations. For example, the compose element of a ValueSet is a computable definition of the members of the value set. Because the computable capabilities of each type of knowledge artifact vary based on what the knowledge artifact is representing, guidance on individual elements for each profile are defined in the computable profiles.

Executable

For knowledge artifacts an executable artifact identifies the aspects of the artifact that are primarily focused on implementation or run-time considerations. For example, the expansion element of a ValueSet is an explicit representation of the members of the value set for a particular expansion (i.e. without requiring the use of a terminology server to understand the computable definition). Because the executable capabilities of each type of knowledge artifact vary based on what the knowledge artifact is representing, guidance on individual elements for each profile are defined in the executable profile.

Artifact Capability Profiles

The following table lists the capability profiles defined for each type of knowledge artifact:

ArtifactShareableComputablePublishableExecutable
ActivityDefinitionCRMIShareableActivityDefinitionN/A (no requirements)CRMIPublishableActivityDefinitionN/A (no requirements)
CapabilityStatementCRMIShareableCapabilityStatementN/A (no requirements)CRMIPublishableCapabilityStatementN/A (no requirements)
ClinicalUseDefinitionCRMIShareableClinicalUseDefinition (Roadmap Item)N/A (no requirements)CRMIPublishableClinicalUseDefinition (Roadmap Item)N/A (no requirements)
CodeSystemCRMIShareableCodeSystemN/A (no requirements)CRMIPublishableCodeSystemN/A (no requirements)
CompartmentDefinitionCRMIShareableCompartmentDefinition (Roadmap Item)N/A (no requirements)CRMIPublishableCompartmentDefinition (Roadmap Item)N/A (no requirements)
ConditionDefinitionCRMIShareableConditionDefinition (Roadmap Item)N/A (no requirements)CRMIPublishableConditionDefinition (Roadmap Item)N/A (no requirements)
ConceptMapCRMIShareableConceptMapN/A (no requirements)CRMIPublishableConceptMapN/A (no requirements)
DeviceDefinitionCRMIShareableDeviceDefinition (Roadmap Item)N/A (no requirements)CRMIPublishableDeviceDefinition (Roadmap Item)N/A (no requirements)
ExampleScenarioCRMIShareableExampleScenario (Roadmap Item)N/A (no requirements)CRMIPublishableExampleScenario (Roadmap Item)N/A (no requirements)
GraphDefinitionCRMIShareableGraphDefinitionN/A (no requirements)CRMIPublishableGraphDefinitionN/A (no requirements)
GroupCRMIShareableGroup (Roadmap Item)N/A (no requirements)CRMIPublishableGroup (Roadmap Item)N/A (no requirements)
ImplementationGuideCRMIShareableImplementationGuideN/A (no requirements)CRMIPublishableImplementationGuideN/A (no requirements)
LibraryCRMIShareableLibraryCRMIComputableLibraryCRMIPublishableLibraryCRMIExecutableLibrary
MeasureCRMIShareableMeasureN/A (no requirements)CRMIPublishableMeasureN/A (no requirements)
MedicationCRMIShareableMedication (Roadmap Item)N/A (no requirements)CRMIPublishableMedication (Roadmap Item)N/A (no requirements)
MedicationKnowledgeCRMIShareableMedicationKnowledge (Roadmap Item)N/A (no requirements)CRMIPublishableMedicationKnowledge (Roadmap Item)N/A (no requirements)
MessageDefinitionCRMIShareableMessageDefinition (Roadmap Item)N/A (no requirements)CRMIPublishableMessageDefinition (Roadmap Item)N/A (no requirements)
NamingSystemCRMIShareableNamingSystemN/A (no requirements)CRMIPublishableNamingSystemN/A (no requirements)
ObservationDefinitionCRMIShareableObservationDefinition (Roadmap Item)N/A (no requirements)CRMIPublishableObservationDefinition (Roadmap Item)N/A (no requirements)
OperationDefinitionCRMIShareableOperationDefinitionN/A (no requirements)CRMIPublishableOperationDefinitionN/A (no requirements)
PlanDefinitionCRMIShareablePlanDefinitionN/A (no requirements)CRMIPublishablePlanDefinitionN/A (no requirements)
QuestionnaireCRMIShareableQuestionnaireN/A (no requirements)CRMIPublishableQuestionnaireN/A (no requirements)
SearchParameterCRMIShareableSearchParameterN/A (no requirements)CRMIPublishableSearchParameterN/A (no requirements)
SpecimenDefinitionCRMIShareableSpecimenDefinition (Roadmap Item)N/A (no requirements)CRMIPublishableSpecimenDefinition (Roadmap Item)N/A (no requirements)
SubstanceCRMIShareableSubstance (Roadmap Item)N/A (no requirements)CRMIPublishableSubstance (Roadmap Item)N/A (no requirements)
SubscriptionTopicCRMIShareableSubscriptionTopic (Roadmap Item)N/A (no requirements)CRMIPublishableSubscriptionTopic (Roadmap Item)N/A (no requirements)
StructureDefinitionCRMIShareableStructureDefinitionN/A (no requirements)CRMIPublishableStructureDefinitionN/A (no requirements)
StructureMapCRMIShareableStructureMap (Roadmap Item)N/A (no requirements)CRMIPublishableStructureMap (Roadmap Item)N/A (no requirements)
TerminologyCapabilitiesCRMIShareableTerminologyCapabilitiesN/A (no requirements)CRMIPublishableTerminologyCapabilitiesN/A (no requirements)
ValueSetCRMIShareableValueSetCRMIComputableValueSetCRMIPublishableValueSetCRMIExpandedValueSet

Note that the terminology-related profiles (on CodeSystem, ConceptMap, NamingSystem, and ValueSet) are defined to support usage in R4 implementations. These profiles are aligned with the same profiles defined in the R6 base specification, and when an R6 version of this implementation guide is produced, these profiles will be removed from this IG in favor of the R6 profiles in the base specification.

Artifact Definition Profiles

To support packaging, testing, and distribution of knowledge artifacts, this implementation guide defines the following additional profiles:

ProfileDescription
CRMIGroupDefinitionA profile of Group that supports context-independent representation of groups for use in definitional contexts.
CRMIManifestLibraryA library profile used to define artifact collections that provide complete dependency and version resolution information for the artifacts in the collection.
CRMIMedicationDefinitionA profile of Medication that supports context-independent representation of medications for use in definitional contexts.
CRMIMedicationKnowledgeDefinitionA profile of MedicationKnowledge that supports context-independent representation of medication knowledge for use in definitional contexts.
CRMIModuleConfigurationLibraryA library profile used to define and exchange configuration information for an artifact (or collection of artifacts) for a specific endpoint.
CRMIModuleDefinitionLibraryA library profile used to define and exchange effective data requirements and usage information for an artifact (or collection of artifacts).
CRMISoftwareSystemDeviceA software device used in the creation, validation, evaluation, packaging, and/or testing of a library or measure artifact.
CRMISubstanceDefinitionA profile of Substance that supports context-independent representation of substances for use in definitional contexts