Canonical URL Compliance Checklist for FHIR Implementation Guides

✅ 1. Uniqueness & Stability

• Canonical URL is globally unique.
• URL remains stable across all IG versions.
• URL is not reused for unrelated content.

---

✅ 2. Format & Structure

• URL is an absolute URI (e.g., https://example.org/fhir/ig-name).
• Uses HTTPS.
• No version info in the base URL (use ImplementationGuide.version instead).

---

✅ 3. Domain Ownership

• Domain is under your control or an authorized domain (e.g., hl7.org).
• Avoid temporary or personal domains.

---

✅ 4. Resolvability (Best Practice)

• Canonical URL resolves to a useful resource, such as:
  • IG homepage (HTML)
  • CapabilityStatement or package manifest
• Supports machine-readable access (e.g., package.tgz).

---

✅ 5. Persistence & FAIR Principles

• URL is persistent and long-term.
• Aligns with FAIR principles: globally unique, persistent, ideally resolvable.

---

✅ 6. Documentation

• Canonical URL declared in ImplementationGuide.url.
• Governance and stability policy documented in IG publishing notes.

---

✅ Do & Don’t Examples

✅ Do:

• https://example.org/fhir/ig-name
• https://hl7.org/fhir/uv/myguide
• https://health.gov.au/fhir/ig/medications

❌ Don’t:

• http://example.org/fhir/ig-name (use HTTPS)
• https://example.org/fhir/ig-name/v1 (don’t include version in URL)
• https://github.com/user/repo/blob/main/ig (avoid temporary or personal domains)
• urn:uuid:1234-5678-90ab (allowed but not recommended for IGs)

---

References

Here are the key references from the official FHIR specification and best practice guides regarding canonical URLs for Implementation Guides (IGs):

---

1. FHIR Specification – CanonicalResource

• The url element in a CanonicalResource (which includes ImplementationGuide) is:
  • An absolute URI that uniquely identifies the resource.
  • SHOULD be globally unique and SHOULD be a literal address at which an authoritative instance of this resource is (or will be) published.
  • Real HTTP(S) addresses are preferred, though urn:uuid: or urn:oid: are allowed.
  • Even if the resource is moved, the canonical URL must remain stable.[1](https://www.hl7.org/fhir/R5/canonicalresource-definitions.html)

---

2. HL7 Guidance on IG Publishing

• HL7 assigns a canonical URL for IGs published on hl7.org or fhir.org.
• The canonical URL is the ongoing home of the IG across multiple versions.
• IGs SHALL declare this canonical URL in the ImplementationGuide.url element.[2](https://confluence.hl7.org/spaces/FHIR/pages/66930646/FHIR+Implementation+Guide+Publishing+Requirements)

---

3. Best Practices for Choosing Canonical URLs

• Use a domain you control (e.g., example.org/fhir/your-ig).
• Prefer HTTPS for security and consistency.
• Keep the URL stable and avoid reusing it for unrelated content.
• While not mandatory, making the canonical URL resolvable is strongly recommended for usability and FAIR principles.[3](https://fire.ly/blog/how-to-choose-the-right-canonical-url-for-your-fhir-specification/)

---

4. FAIR Principles and Resolvability

• FAIR principles require identifiers to be globally unique, persistent, and machine-resolvable.
• FHIR canonical URLs fulfill uniqueness and persistence, but resolvability depends on the publisher.
• Best practice: ensure the canonical URL resolves to the IG homepage or a machine-readable artifact.[4](https://confluence.hl7.org/spaces/SOA/pages/118981003/FHIR+identifiers+and+FAIR+principles+on+IDs)

---

✅ Summary:

• Not strictly required to be resolvable, but strongly recommended.
• Canonical URL must remain stable and globally unique.
• Preferred pattern: https://your-domain/fhir/ig-name.