Skip to main content

Canonical URLs

Status

Ready for review

info

'Canonical' here means well-known (among consumers of a FHIR API).

Many FHIR resource types define a canonical URL, also known in FHIR Implementation Guides as official URLs, which API consumers can rely on to permanently identify a resource across all contexts of use.

FHIR APIs MUST use canonical URLs to reference recognised resource instances. See Canonical Resource Identity in the FHIR documentation for further information.

Two practical examples where use of a canonical URL is crucial:

  1. When a FHIR API consumer is creating a QuestionnaireResponse resource instance and needs to identify the Questionnaire which defines the standard questions answered by that response.
  2. When a FHIR API designer needs to identify a ValueSet resource which specifies codes (aka 'terminology') valid for use in some particular situation.

Requirements for FHIR APIs​

  1. FHIR API designers MUST define and use recognised canonical URLs in new definitions (profiles and extensions) and terminology (CodeSystems and ValueSets)

  2. Canonical URLs SHOULD use a standards.digital.health.nz base.

Canonical URL naming pattern​

IG artifact typeOfficial Url naming pattern to use
Extension (StructureDefinition)http://standards.digital.health.nz/fhir/StructureDefinition/{{extensionName}}
CodeSystemhttp://standards.digital.health.nz/ns/{{CodeSystemName}}
ValueSethttp://nzhts.digital.health.nz/fhir/ValueSet/{{ValueSetName}}