Canonical URL governance

Purpose

A FHIR canonical URL is the stable, globally unique identity of a conformance or knowledge artefact. It is not the Simplifier page URL, a FHIR server location, or an example resource fullUrl.

For DigiDOT, canonical URLs identify profiles, extensions, ValueSets, CodeSystems, the CapabilityStatement and the OperationDefinition. Other profiles and instances refer to those identities through fields such as meta.profile, baseDefinition, targetProfile, binding.valueSet and type.profile.

DigiDOT decision

The DigiDOT canonical base is:

https://novari.no/fhir/digidot

Use this pattern for every DigiDOT canonical artefact:

https://novari.no/fhir/digidot/{resourceType}/{id}

Examples:

https://novari.no/fhir/digidot/StructureDefinition/digidot-Procedure-no
https://novari.no/fhir/digidot/ValueSet/dental-procedures
https://novari.no/fhir/digidot/CodeSystem/digidot-procedure-category

The package manifest uses the same base in its canonical property. Draft examples use HTTPS instance addresses below https://novari.no/fhir/digidot/example/... when an absolute Bundle fullUrl is useful. Those example addresses are not canonical artefact identities.

Scope and ownership

Use this base only for DigiDOT artefacts that DigiDOT/Novari governs. Do not change canonical URLs belonging to other publishers. In particular, no-basis and SFM artefacts retain their published http://hl7.no/fhir/... or http://ehelse.no/fhir/... identities even when DigiDOT references them from an HTTPS URL.

The organisation that claims the base must control the novari.no namespace for the lifetime of the published artefacts. This is a governance decision: once an artefact is used outside the draft, its canonical URL must remain unchanged. Change the artefact version for a compatible revision; create a new artefact only when its identity or meaning changes.

The draft payment-rule CodeSystem and ValueSet were normalized from HTTP to HTTPS before production use. Their old HTTP identifiers must not be introduced into new examples, bindings or implementations.

Simplifier canonical claim

Simplifier claims prove the project is authorised to use a canonical base. The claim does not itself create a FHIR endpoint, redirect novari.no, register a national standard or grant formal conformance approval.

After the project owner confirms the DigiDOT/Novari ownership decision, complete the claim in Simplifier:

  1. Sign in with a project owner or manager account for DigiDOT - Norwegian Public Dental Service.
  2. Open Manage and choose Canonical claims.
  3. Select the suggested Simplifier claim https://novari.no/fhir/digidot/, including the final slash. It is the prefix that covers the DigiDOT artefact URLs. The FHIR package canonical base remains https://novari.no/fhir/digidot without the final slash; individual artefact URLs append /{resourceType}/{id}. Do not make separate claims for StructureDefinition, ValueSet or individual resources.
  4. Verify the claim is shown as valid on the project page and that resource pages no longer show that their canonical URL can still change.
  5. When a versioned package is released, repeat the ownership check under the package's Administration area and claim the same base there where Simplifier offers it.

Do not claim https://novari.no/fhir, https://novari.no, or any base belonging to another publisher. Those claims are broader than the DigiDOT artefact namespace.

Publication and implementation rules

  • Use HTTPS for every DigiDOT canonical URL, canonical reference and absolute DigiDOT example fullUrl.
  • Use the canonical URL, not the Simplifier page address, in FHIR artefacts and implementation configuration.
  • Keep id, canonical url, name and source filename aligned. The canonical URL is formed from the resource type and id.
  • Do not include a |version suffix in meta.profile, baseDefinition, targetProfile or normal ValueSet bindings unless a specific version lock is deliberately required. The artefact's version is carried on the canonical resource itself.
  • When a new DigiDOT artefact is added, set its HTTPS canonical url, add it to the package/guide where relevant, and check that all internal references resolve to the same URL.
  • Configure a stable documentation or redirect service for https://novari.no/fhir/digidot/... before production publication where possible. Simplifier's documentation redirection improves simplifier.net/resolve, but it is separate from operating the novari.no URL itself.

Current quality checks

Before synchronizing or releasing the package, verify that:

  1. Every DigiDOT canonical resource URL begins with https://novari.no/fhir/digidot/.
  2. No insecure HTTP variant of the DigiDOT canonical base remains in profiles, terminology resources, examples, guides or review exports.
  3. There are no duplicate canonical URLs.
  4. Each internal binding.valueSet, targetProfile, type.profile, baseDefinition and meta.profile reference points to the intended canonical artefact.
  5. Simplifier reports the project claim as valid after synchronization.

References