Release 5

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

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

2.1.27.7.4 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. CanonicalResource «I»NDomainResourceCommon 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 ΣC0..1uriCanonical 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..*IdentifierAdditional identifier for the {{title}}

... version Σ0..1stringBusiness version of the {{title}}
.... versionAlgorithmStringstring
.... versionAlgorithmCodingCoding
... name ΣC0..1stringName for this {{title}} (computer friendly)
... title Σ0..1stringName for this {{title}} (human friendly)
... status ?!Σ1..1codedraft | active | retired | unknown
Binding: PublicationStatus (Required)
... experimental Σ0..1booleanFor testing purposes, not real usage
... date Σ0..1dateTimeDate last changed
... publisher Σ0..1stringName of the publisher/steward (organization or individual)
... contact Σ0..*ContactDetailContact details for the publisher

... description 0..1markdownNatural language description of the {{title}}
... useContext Σ0..*UsageContextThe context that the content is intended to support

... jurisdiction ΣXD0..*CodeableConceptIntended jurisdiction for {{title}} (if applicable)
Binding: Jurisdiction ValueSet (Extensible)

... purpose 0..1markdownWhy this {{title}} is defined
... copyright 0..1markdownUse and/or publishing restrictions
... copyrightLabel T0..1stringCopyright holder and year(s)

doco Documentation for this format icon

UML Diagram (Legend)

CanonicalResource (DomainResource) «Interface»An absolute URI that is used to identify this {{title}} when it is referenced in a specification, model, design or an instance; also called its canonical identifier. This SHOULD be globally unique and SHOULD be a literal address at which an authoritative instance of this {{title}} is (or will be) published. This URL can be the target of a canonical reference. It SHALL remain the same when the {{title}} is stored on different serversurl : uri [0..1]A formal identifier that is used to identify this {{title}} when it is represented in other formats, or referenced in a specification, model, design or an instanceidentifier : Identifier [0..*]The identifier that is used to identify this version of the {{title}} when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the {{title}} author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. There is also no expectation that versions can be placed in a lexicographical sequence without additional knowledge. (See the versionAlgorithm element.)version : string [0..1]Indicates the mechanism used to compare versions to determine which is more currentversionAlgorithm[x] : DataType [0..1] « string|Coding; null (Strength=Extensible) VersionAlgorithm+ »A natural language name identifying the {{title}}. This name should be usable as an identifier for the resource by machine processing applications such as code generationname : string [0..1] « This element has or is affected by some invariantsC »A short, descriptive, user-friendly title for the {{title}}title : string [0..1]The current state of this {{title}}. (this element modifies the meaning of other elements)status : code [1..1] « null (Strength=Required)PublicationStatus! »A Boolean value to indicate that this {{title}} is authored for testing purposes (or education/evaluation/marketing) and is not intended for genuine usageexperimental : boolean [0..1]The date (and optionally time) when the {{title}} was last significantly changed. The date must change when the business version changes and it must change if the status code changes. In addition, it should change when the substantive content of the {{title}} changesdate : dateTime [0..1]The name of the organization or individual responsible for the release and ongoing maintenance of the {{title}}publisher : string [0..1]Contact details to assist a user in finding and communicating with the publishercontact : ContactDetail [0..*]A free text natural language description of the {{title}} from a consumer's perspectivedescription : markdown [0..1]The content was developed with a focus and intent of supporting the contexts that are listed. These contexts may be general categories (gender, age, ...) or may be references to specific programs (insurance plans, studies, ...) and may be used to assist with indexing and searching for appropriate {{title}}suseContext : UsageContext [0..*]A legal or geographic region in which the {{title}} is intended to be usedjurisdiction : CodeableConcept [0..*] « null (Strength=Extensible)JurisdictionValueSet+ »Explanation of why this {{title}} is needed and why it has been designed as it haspurpose : markdown [0..1]A copyright statement relating to the {{title}} and/or its contents. Copyright statements are generally legal restrictions on the use and publishing of the {{title}}copyright : markdown [0..1]A short string (<50 characters), suitable for inclusion in a page footer that identifies the copyright holder, effective period, and optionally whether rights are resctricted. (e.g. 'All rights reserved', 'Some rights reserved')copyrightLabel : string [0..1]

Changes from both R4 and R4B

This resource did not exist in Release R4

See the Full Difference for further information

This analysis is available for R4 as XML or JSON and R4B as XML or JSON.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. CanonicalResource «I»NDomainResourceCommon 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 ΣC0..1uriCanonical 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..*IdentifierAdditional identifier for the {{title}}

... version Σ0..1stringBusiness version of the {{title}}
.... versionAlgorithmStringstring
.... versionAlgorithmCodingCoding
... name ΣC0..1stringName for this {{title}} (computer friendly)
... title Σ0..1stringName for this {{title}} (human friendly)
... status ?!Σ1..1codedraft | active | retired | unknown
Binding: PublicationStatus (Required)
... experimental Σ0..1booleanFor testing purposes, not real usage
... date Σ0..1dateTimeDate last changed
... publisher Σ0..1stringName of the publisher/steward (organization or individual)
... contact Σ0..*ContactDetailContact details for the publisher

... description 0..1markdownNatural language description of the {{title}}
... useContext Σ0..*UsageContextThe context that the content is intended to support

... jurisdiction ΣXD0..*CodeableConceptIntended jurisdiction for {{title}} (if applicable)
Binding: Jurisdiction ValueSet (Extensible)

... purpose 0..1markdownWhy this {{title}} is defined
... copyright 0..1markdownUse and/or publishing restrictions
... copyrightLabel T0..1stringCopyright holder and year(s)

doco Documentation for this format icon

UML Diagram (Legend)

CanonicalResource (DomainResource) «Interface»An absolute URI that is used to identify this {{title}} when it is referenced in a specification, model, design or an instance; also called its canonical identifier. This SHOULD be globally unique and SHOULD be a literal address at which an authoritative instance of this {{title}} is (or will be) published. This URL can be the target of a canonical reference. It SHALL remain the same when the {{title}} is stored on different serversurl : uri [0..1]A formal identifier that is used to identify this {{title}} when it is represented in other formats, or referenced in a specification, model, design or an instanceidentifier : Identifier [0..*]The identifier that is used to identify this version of the {{title}} when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the {{title}} author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. There is also no expectation that versions can be placed in a lexicographical sequence without additional knowledge. (See the versionAlgorithm element.)version : string [0..1]Indicates the mechanism used to compare versions to determine which is more currentversionAlgorithm[x] : DataType [0..1] « string|Coding; null (Strength=Extensible) VersionAlgorithm+ »A natural language name identifying the {{title}}. This name should be usable as an identifier for the resource by machine processing applications such as code generationname : string [0..1] « This element has or is affected by some invariantsC »A short, descriptive, user-friendly title for the {{title}}title : string [0..1]The current state of this {{title}}. (this element modifies the meaning of other elements)status : code [1..1] « null (Strength=Required)PublicationStatus! »A Boolean value to indicate that this {{title}} is authored for testing purposes (or education/evaluation/marketing) and is not intended for genuine usageexperimental : boolean [0..1]The date (and optionally time) when the {{title}} was last significantly changed. The date must change when the business version changes and it must change if the status code changes. In addition, it should change when the substantive content of the {{title}} changesdate : dateTime [0..1]The name of the organization or individual responsible for the release and ongoing maintenance of the {{title}}publisher : string [0..1]Contact details to assist a user in finding and communicating with the publishercontact : ContactDetail [0..*]A free text natural language description of the {{title}} from a consumer's perspectivedescription : markdown [0..1]The content was developed with a focus and intent of supporting the contexts that are listed. These contexts may be general categories (gender, age, ...) or may be references to specific programs (insurance plans, studies, ...) and may be used to assist with indexing and searching for appropriate {{title}}suseContext : UsageContext [0..*]A legal or geographic region in which the {{title}} is intended to be usedjurisdiction : CodeableConcept [0..*] « null (Strength=Extensible)JurisdictionValueSet+ »Explanation of why this {{title}} is needed and why it has been designed as it haspurpose : markdown [0..1]A copyright statement relating to the {{title}} and/or its contents. Copyright statements are generally legal restrictions on the use and publishing of the {{title}}copyright : markdown [0..1]A short string (<50 characters), suitable for inclusion in a page footer that identifies the copyright holder, effective period, and optionally whether rights are resctricted. (e.g. 'All rights reserved', 'Some rights reserved')copyrightLabel : string [0..1]

Changes from both R4 and R4B

This resource did not exist in Release R4

See the Full Difference for further information

This analysis is available for R4 as XML or JSON and R4B as XML or JSON.

 

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

2.1.27.7.4.1 Terminology Bindings

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

NameTypeDescriptionPaths
contexttokenA use context assigned to the {{title}}{{name}}.useContext.valueCodeableConcept
context-quantityquantityA quantity- or range-valued use context assigned to the {{title}}{{name}}.useContext.valueQuantity, {{name}}.useContext.valueRange
context-referencereferenceA use context reference assigned to the {{title}}
context-typetokenA type of use context assigned to the {{title}}{{name}}.useContext.code
context-type-quantitycompositeA use context type and quantity- or range-based value assigned to the {{title}}
context-type-valuecompositeA use context type and value assigned to the {{title}}
datedateThe {{title}} publication date{{name}}.date
descriptionstringThe description of the {{title}}{{name}}.description
identifiertokenExternal identifier for the {{title}}{{name}}.identifier
jurisdictiontokenIntended jurisdiction for the {{title}}{{name}}.jurisdiction
namestringComputationally friendly name of the {{title}}{{name}}.name
publisherstringName of the publisher of the {{title}}{{name}}.publisher
statustokenThe current status of the {{title}}{{name}}.status
titlestringThe human-friendly name of the {{title}}{{name}}.title
urluriThe uri that identifies the {{title}}{{name}}.url
versiontokenThe business version of the {{title}}{{name}}.version