type: resourceresource: CanonicalResource

CanonicalResource

Scope and Usage

The CanonicalResource represents resources that have a canonical URL:

They have a canonical URL (note: all resources with a canonical URL are specializations of this type)
They have version, status, and data properties to help manage their publication
They carry some additional metadata about their use, including copyright information

As an interface, this type is never created directly - see Resource Interfaces for more details.

Boundaries and Relationships

This interface extends the base DomainResource. The following resources implement this interface:

Other Additional Resources may implement CanonicalResource. See the list here

All of the elements reflected on a canonical resource are the assertions as made by the original author/publisher and do NOT reflect divergent local usage expectations. If a system has a need to capture local usage requirements (e.g. local deprecation, local 'active' use past the point of deprecation/retirement by the official source, alternative effective periods, etc.), those assertions should be made in a separate resource (e.g. List, ArtifactAssessment, etc.) that focuses on approval/usage of referenced resources, not on the canonical/metadata resource itself. Alternatively, a separate resource might be defined that 'derives' from the original resource and can have its own properties.

There is however, a possibility of local changes on 'generated' elements such as ValueSet expansions, StructureDefinition snapshots, etc. In this case:

If the source of truth is providing expansions, snapshot generation or similar "generated" elements, then it is not a good idea for downstream servers to update/override them.
If the source of truth is NOT providing those generated elements, then it is reasonable for downstream servers to generate them (and update them from time to time). If this happens, it is possible that different servers will have different generated elements. This would not be considered a violation of the guidelines proposed above.

HL7 is developing a [Canonical Resource Management]([%ig crmi%]) implementation guide to define best practices for asserting and exposing local usage expectations of canonical and metadata resources. Readers are invited to consult the current release of that IG for additional guidance.

Version Comparison

Canonical resources may have both a version, and a version algorithm. In normal usage, implementers are strongly recommended to version all the canonical resources that they maintain. The difference between the CanonicalResource version (business version) and the Resource version in .meta.version is discussed on Resource.

The version algorithm allows applications to choose the correct latest version of a resource, since there is no general algorithm that chooses the latest version across all versioning schemes in place.

Implementers are encouraged to use semantic versioning, but may have existing approaches that are already adopted.

[%impl-note%] This mechanism we have for defining version comparison algorithm, where each version of the resource makes its own claim about how version comparison works is inelegant and feels somewhat clunky, but that was the best that the committee identified that would work in all circumstances. Alternative proposals that could be used to address the problem that would be less onerous are welcome. [%end-note%]

StructureDefinition

Elements (Simplified)

CanonicalResource [1..1]: - Common Interface declaration for definitional resources
CanonicalResource.url [0..1]: uri Canonical identifier for this {{title}}, represented as an absolute URI (globally unique)
CanonicalResource.identifier [0..*]: Identifier Additional identifier for the {{title}}
CanonicalResource.version [0..1]: string Canonical version of the {{title}}
CanonicalResource.versionAlgorithm[x] [0..1]: string, Coding extensible:version-algorithm How to compare versions
CanonicalResource.name [0..1]: string Name for this {{title}} (computer friendly)
CanonicalResource.title [0..1]: string Name for this {{title}} (human friendly)
CanonicalResource.status [1..1]: code required:publication-status draft | active | retired | unknown
CanonicalResource.experimental [0..1]: boolean For testing only - never for real usage
CanonicalResource.date [0..1]: dateTime Date last changed
CanonicalResource.publisher [0..1]: string Name of the publisher/steward (organization or individual)
CanonicalResource.contact [0..*]: ContactDetail Contact details for the publisher
CanonicalResource.description [0..1]: markdown Natural language description of the {{title}}
CanonicalResource.useContext [0..*]: UsageContext The context that the content is intended to support
CanonicalResource.jurisdiction [0..*]: CodeableConcept extensible:jurisdiction Jurisdiction of the authority that maintains the {{title}} (if applicable)
CanonicalResource.purpose [0..1]: markdown Why this {{title}} is defined
CanonicalResource.copyright [0..1]: markdown Notice about intellectual property ownership, can include restrictions on use
CanonicalResource.copyrightLabel [0..1]: string Copyright holder and year(s)

Mappings

CanonicalResource Mappings — 12 mapping entries

Implementation Guide

implementationguide-CanonicalResource-core.xml

<?xml version="1.0" encoding="UTF-8"?>

<ImplementationGuide xmlns="http://hl7.org/fhir">
  <id value="CanonicalResource-core"/>
  <name value="CommonCanonicalResourceExtensions"/>
  <title value="Common  Canonical Resource extensions"/>
  <status value="draft"/>
  <date value="2014-04-12T00:00:00.000"/>
  <publisher value="Health Level Seven, Inc. - [WG Name] WG"/>
  <description value="Common extensions for use with the CanonicalResource resource"/>
</ImplementationGuide>

Operations

current-canonical — Fetch the current version of a canonical resource (based on canonical versioning) — Returns the most current version of the canonical resource with the specified url available on the server.

Full Operations

Resource Packs

list-CanonicalResource-packs.xml

<?xml version="1.0" encoding="UTF-8"?>

<List xmlns="http://hl7.org/fhir">
  <id value="CanonicalResource-packs"/>
  <status value="current"/>
  <mode value="working"/>
  <entry>
    <item>
      <reference value="ImplementationGuide/CanonicalResource-core"/>
    </item>
  </entry>
</List>

Search Parameters

context — token — A use context assigned to the {{title}} — ({{name}}.useContext.value.ofType(CodeableConcept))
context-quantity — quantity — A quantity- or range-valued use context assigned to the {{title}} — ({{name}}.useContext.value.ofType(Quantity)) | ({{name}}.useContext.value.ofType(Range))
context-type — token — A type of use context assigned to the {{title}} — {{name}}.useContext.code
context-type-quantity — composite — A use context type and quantity- or range-based value assigned to the {{title}} — {{name}}.useContext
context-type-value — composite — A use context type and value assigned to the {{title}} — {{name}}.useContext
context-reference — reference — A use context reference assigned to the {{title}} — {{name}}.useContext.value
date — date — The {{title}} publication date — {{name}}.date
description — string — The description of the {{title}} — {{name}}.description
identifier — token — External identifier for the {{title}} — {{name}}.identifier
jurisdiction — token — Jurisdiction of the authority that maintains the the {{title}} — {{name}}.jurisdiction
name — string — Computationally friendly name of the {{title}} — {{name}}.name
publisher — string — Name of the publisher of the {{title}} — {{name}}.publisher
status — token — The current status of the {{title}} — {{name}}.status
title — string — The human-friendly name of the {{title}} — {{name}}.title
url — uri — The uri that identifies the {{title}} — {{name}}.url
version — token — The business version of the {{title}} — {{name}}.version

Full Search Parameters