This page is part of the Quality Measure STU2 for FHIR R4 Implementation Guide (v4.0.0: STU4 (v4.0.0)) based on FHIR R4. This is the current published version in its permanent home (it will always be available at this URL). For a full list of available versions, see the Directory of published versions
This page documents the use cases and conformance expectations of a measure repository service to support authoring, publishing, and distribution of FHIR-based quality measure specifications as described in this implementation guide.
The measure repository service described here is a specific case of the more general knowledge repository service. The operations and capabilities described are in terms of measures and libraries specifically, but they can be generally applied to other knowledge artifacts as well, such as PlanDefinition, StructureDefinition, ValueSet, and others.
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.
Quality measures (QMs) are a specific type of knowledge artifact, and share common attributes with other knowledge artifact types. 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 vesrion-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 $cqfm.package operation supports the ability of a repository to package an artifact for a particular target environment, and with required components and dependencies included. 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.system-version: Specifies a version to use for a system, if the library or value set does not already specify which one to use. The format is the same as a canonical URL: [system] | [version] - e.g. http://loinc.org | 2.56 |
check-system-version: Edge Case: Specifies a version to use for a system. If a library or value set specifies 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 |
force-system-version: Edge Case: Specifies a version to use for a system. This parameter overrides any specified version in the library and value sets (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 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.
For the $cqfm.package operation, when combinations of “in” parameters specify more than one measure to package, the operation SHOULD return an OperationOutcome error. These combinations include the following:
Implementations are not required to support mixing of “in” parameters in the URL and inside a POSTed Parameters resource; it is acceptable to return an OperationOutcome if mixing is not supported. Implementation MAY support such mixing of input parameters.
These constraints are applicable even if if some or all of the in parameters are specified in the URL
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:
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. Child artifacts (i.e. artifacts that compose the existing artifact) are expected to be present in the server, or may be submitted as part of a transaction or collection batch.
The draft operation supports creating 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 no version. It is an error to create multiple drafts of the same artifact by URL. Child artifacts (i.e. artifacts that compose the existing artifact) are also drafted, recursively. Note that although it should be the case that all child artifacts of an active artifact are also active, in the case that a child artifact is already draft, the operation simply copies the reference to the draft artifact.
The clone operation supports creating a new draft artifact based on the contents of an existing artifact, regardless of status, with a new URL. This operation creates a new resource with the same contets as the existing artifact, but with a status of draft, no version, and the new URL. Child artifacts (i.e. artifacts that compose the existing artifact) are also cloned, recursively, by constructing a new URL for each child artifact that is cloned (as opposed to dependencies, for which the refernces are just copied).
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. Updates to child artifacts (i.e. artifacts that compose the artifact) are expected to be performed via separate revise operations, or may be revised as part of a transaction or collection batch.
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. Child artifacts (i.e. artifacts that compose the existing artifact) are expected to be withdrawn via separate withdraw operations, or may be withdrawn as part of a transaction or collection batch.
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.
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 artifactComment elements to the artifact, and to add or update an endorser. Child artifacts (i.e. artifacts that compose the artifact) are expected to be approved via separate operations, or may be approved as part of a transaction or collection batch.
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. Child artifacts (i.e. artifacts that compose the existing artifact) are expected to be present in the server, or may be published as part of a transaction or collection batch.
The release operation supports updating the status of an existing draft artifact to active. The operation sets the date and status elements of the artifact, but is otherwise not allowed to change any other elements of the artifact. Child artifacts (i.e. artifacts that compose the existing artifact) are also released, recursively. To be released, an artifact is required to have a version specified.
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. Child artifacts (i.e. artifacts that compose the existing artifact) are expected to retired via separate retire operations, or may be retired as part of a transaction or collection batch.
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. Child artifacts (i.e. artifacts that compose the existing artifact) are expected to archived via separate archive operations, or may be archived as part of a transaction or collection batch.
The ShareableMeasureRepository capability statement defines the minimum expectations for a measure repository that provides basic access to shareable measure content. It describes the minimum required functionality for sharing FHIR-based measure content.
The CQFMShareableMeasureRepository capability statement captures these requirements formally, while the following sections provide a narrative description of them.
A ShareableMeasureRepository:
SHALL Represent basic Library information, as specified by the CQFMLibrary profile, which includes url, identifier, version, name, title, type, status, experimental, date, publisher, contact, description, useContext, and jurisdiction.
For computable libraries, SHALL represent computable Library information, as specified by the CQFMComputableLibrary profile.
For executable libraries, SHALL represent executable Library information, as specified by the CQFMExecutableLibrary profile.
For published libraries, SHALL represent publishable Library information, as specified by the CQFMPublishableLibrary profile.
SHALL support Library read by the server-defined id for the Library
SHALL support Library searches by:
A ShareableMeasureRepository:
SHALL Represent basic Measure information, as specified by the CQFMMeasure profile, which includes url, identifier, version, name, title, type, status, experimental, date, publisher, contact, description, useContext, and jurisdiction.
For computable measures, SHALL represent computable Measure information, as specified by the CQFMComputableMeasure profile.
For published measures, SHALL represent publishable Measure information, as specified by the CQFMPublishableMeasure profile.
SHALL support Measure read by the server-defined id for the Measure
SHALL support Measure searches by:
The PublishableMeasureRepository capability statement expresses additional functionality that SHOULD be provided in support of providing published FHIR quality measures including additional searching and packaging capabilities.
The CQFMPublishableMeasureRepository capability statement captures these requirements formally, while the following sections provide a narrative description of them.
A PublishableMeasureRepository:
A PublishableMeasureRepository:
A PublishableMeasureRepository:
MAY support representation of test cases using the CQFMTestCase profile.
MAY support retrieval of test cases by server-specific id through the MeasureReport/read interaction
MAY support searching of test cases by the measure
search parameter
MAY support including test cases in measure packages.
MAY support test case packaging: MeasureReport/$cqfm.package operation
The AuthoringMeasureRepository 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 CQFMAuthoringMeasureRepository capability statement captures these requirements formally, while the following sections provide a narrative description of them.
An AuthoringLibraryRepository:
An AuthoringMeasureRepository: