This page is part of the FHIR Specification (v5.0.0: R5 - STU). This is the current published version. For a full list of available versions, see the Directory of published versions

• Content
• Detailed Descriptions
• Mappings
• Operations
• Search Params
• Profiles
• Extensions
• R4 Conversions

2.1.27.7 Resource CanonicalResource - Content

FHIR Infrastructure Work Group

Maturity 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.7.3 References to this Resource

• Extension References: Alternate Canonical

2.1.27.7.4 Resource Content

 

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

2.1.27.7.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 while the codes for "supra-national" regions are from UN Standard country or area codes for statistical use (M49) .

2.1.27.7.4.2 Constraints

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