R6 Ballot (2nd Draft)

Publish-box (todo)

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»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 purposes, not 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

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»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 purposes, not 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

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

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

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