FHIR CI-Build

This is the Continuous Integration Build of FHIR (will be incorrect/inconsistent at times).
See the Directory of published versions icon

2.1.27.6 Resource CanonicalResource - Content

FHIR Infrastructure icon Work GroupMaturity Level: N Normative (from v4.2.0)Security Category: N/A Compartments: No defined compartments

Common Interface declaration for conformance and knowledge artifact resources.

2.1.27.6.1 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.

2.1.27.6.3 References to this Resource

No references for this Resource.

2.1.27.6.4 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. CanonicalResource «I»N DomainResource Common Interface declaration for definitional resources
+ Warning: Name should be usable as an identifier for the module by machine processing applications such as code generation

Elements defined in Ancestor Resources: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... url ΣC 0..1 uri Canonical identifier for this {{title}}, represented as an absolute URI (globally unique)
+ Warning: URL should not contain | or # - these characters make processing canonical references problematic
... identifier Σ 0..* Identifier Additional identifier for the {{title}}

... version Σ 0..1 string Business version of the {{title}}
.... versionAlgorithmString string
.... versionAlgorithmCoding Coding
... name ΣC 0..1 string Name for this {{title}} (computer friendly)
... title Σ 0..1 string Name for this {{title}} (human friendly)
... status ?!Σ 1..1 code draft | active | retired | unknown
Binding: PublicationStatus (Required)
... experimental Σ 0..1 boolean For testing only - never for real usage
... date Σ 0..1 dateTime Date last changed
... publisher Σ 0..1 string Name of the publisher/steward (organization or individual)
... contact Σ 0..* ContactDetail Contact details for the publisher

... description 0..1 markdown Natural language description of the {{title}}
... useContext Σ 0..* UsageContext The context that the content is intended to support

... jurisdiction ΣXD 0..* CodeableConcept Intended jurisdiction for {{title}} (if applicable)
Binding: Jurisdiction ValueSet (Extensible)

... purpose 0..1 markdown Why this {{title}} is defined
... copyright 0..1 markdown Use and/or publishing restrictions
... copyrightLabel T 0..1 string Copyright holder and year(s)

doco Documentation for this format icon

 

Additional definitions: Master Definition XML + JSON, the spreadsheet version & the dependency analysis

2.1.27.6.4.1 Terminology Bindings

Path ValueSet Type Documentation
CanonicalResource.versionAlgorithm[x] VersionAlgorithm Extensible

Indicates the mechanism used to compare versions to determine which is more current.
CanonicalResource.status PublicationStatus Required

The lifecycle status of an artifact.
CanonicalResource.jurisdiction JurisdictionValueSet Extensible

This value set defines a base set of codes for country, country subdivision and region for indicating where a resource is intended to be used.

Note: The codes for countries and country subdivisions are taken from ISO 3166 icon while the codes for "supra-national" regions are from UN Standard country or area codes for statistical use (M49) icon.

2.1.27.6.4.2 Constraints

UniqueKeyLevelLocationDescriptionExpression
img cnl-0Warning (base)Name should be usable as an identifier for the module by machine processing applications such as code generationname.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')
img cnl-1Warning CanonicalResource.urlURL should not contain | or # - these characters make processing canonical references problematicexists() implies matches('^[^|# ]+$')

2.1.27.6.4.3 Localization

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 icon 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.

2.1.27.6.4.4 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.

Implementation 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.

2.1.27.6.5 Search Parameters

Search parameters defined by this interface for all implementations. See Searching for more information about searching in REST, messaging, and services.

Name Type Description Paths
context token A use context assigned to the {{title}} {{name}}.useContext.valueCodeableConcept
context-quantity quantity A quantity- or range-valued use context assigned to the {{title}} {{name}}.useContext.valueQuantity, {{name}}.useContext.valueRange
context-reference reference A use context reference assigned to the {{title}}
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}}
context-type-value composite A use context type and value assigned to the {{title}}
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 Intended jurisdiction for 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