Pattern Catalog

This page provides a high-level overview of all patterns in the FHIR Implementation Patterns collection.

Our FHIR Pattern Collection

Schema-aligned pattern language for authoring HL7® FHIR® Implementation Guides with disciplined repository layout, naming, ADR governance, example placement, FSH usage, reuse/co-authoring across IGs, and robust staging/versioning/CI for GitHub and GitLab.

Key Patterns Covered

Canonical URL and Package ID - Ensure stable discovery and dependency management across IGs by establishing consistent, predictable identifiers from the start of the project.
Standard IG Layout - Keep authors and tools in sync by adopting the HL7 IG Publisher folder schema. When everyone follows the same conventions, onboarding is faster, CI is simpler, and cross-IG contributions become practical.
ADR Log - Make design rationale discoverable and reviewable so that future team members understand why constraints exist, not just what they are. ADRs create an auditable trail of decisions that supports governance and prevents decision debt.
Use Cases and Examples - Organise narrative use cases alongside validated examples
Aliases and RuleSets - Centralise constants and reusable rule blocks to reduce duplication, improve consistency, and make refactoring safer. When terminology URLs and common constraints are defined once, changes propagate automatically.
Extensions and Slicing - Constrain responsibly with clear invariants and named slices
Shared Modules IG - Extract cross-cutting profiles, extensions, and terminology into a shared package that can be versioned and released independently. This enables multiple domain IGs to depend on common definitions without copy-paste duplication.
Co-authoring Workflow - Enable concurrent edits with clear ownership and review
SemVer and Release Channels - Publish predictable versions and previews so consumers know what to expect. CI builds provide instant feedback, snapshots let integrators test against latest, and releases provide stable baselines for production use.
Local Build Parity - Ensure the same toolchain runs locally and in CI
GitHub Actions Pipeline - Establish standard CI for GitHub-hosted IG repositories that builds, validates, and deploys on every push. Reviewers can see rendered output before merging, and releases are automated from tags.

Key Features

Real-world applicable - Patterns based on actual implementation experiences
Standards-aligned - Built on HL7 FHIR, SMART on FHIR, and related healthcare standards
Comprehensive diagrams - PlantUML class and sequence diagrams for each pattern
Forces analysis - Detailed breakdown of the specific problems each pattern solves

Pattern Organization

The patterns in this collection are organized into logical categories by functional area:

Repository & Naming - Conventions for canonical URLs, package ids, branching, and directory layout form the foundation of every IG project. Getting these right early prevents painful migrations later. A well-structured repository enables tooling to work out of the box, helps new team members onboard quickly, and makes CI pipelines straightforward to configure.
Documentation & ADRs - Authoritative documentation lives with the code, and design decisions are captured as Architecture Decision Records (ADRs). When rationale is discoverable in the repository, teams avoid re-litigating past decisions, new members understand 'why' not just 'what', and auditors can trace constraints back to business requirements.
FSH Authoring - FHIR Shorthand (FSH) and SUSHI provide a human-readable, version-control-friendly way to author FHIR profiles, extensions, and instances. These patterns help you write FSH that is maintainable, consistent, and reusable across profiles and projects. Good FSH practices reduce diff noise in code review and make refactoring safer.
Reuse & Co-authoring - When multiple IGs share common profiles, extensions, or terminology, coordination becomes critical. These patterns help you extract shared artifacts into maintainable packages and establish workflows for concurrent editing by distributed teams. Done well, reuse reduces duplication and ensures consistency; done poorly, it creates coupling nightmares.
Staging, Versioning & CI - Reproducible builds are the foundation of reliable IG delivery. These patterns ensure that what works on your laptop works in CI, that consumers can trust version numbers, and that every pull request produces a previewable site. The goal is to eliminate 'works on my machine' problems and give reviewers confidence in what they're approving.
Collaboration & Issues - Well-designed issue templates and PR workflows reduce friction in collaborative IG development. When contributors know what information to provide, triage is faster. When reviewers have checklists, quality is more consistent. These patterns encode team conventions into repository configuration.

Each pattern follows a consistent structure derived from classical pattern literature.

Pattern Philosophy

Our approach follows several key principles:

1. Standards-First

All patterns are built on established healthcare standards:

HL7 FHIR for data exchange and APIs
SMART on FHIR for application authorization
DICOMweb for medical imaging integration
IHE profiles for workflow and security patterns

2. Incremental Adoption

Patterns are designed to support:

Phased implementation and migration strategies
Coexistence with legacy systems
Progressive enhancement of capabilities

3. Real-world Validation

Each pattern addresses documented challenges from actual implementations and includes:

Concrete use cases and scenarios
Performance and scalability considerations
Security and privacy implications

Patterns by Category

Repository & Naming

Conventions for canonical URLs, package ids, branching, and directory layout form the foundation of every IG project. Getting these right early prevents painful migrations later. A well-structured repository enables tooling to work out of the box, helps new team members onboard quickly, and makes CI pipelines straightforward to configure.

Canonical URL and Package ID

Intent: Ensure stable discovery and dependency management across IGs by establishing consistent, predictable identifiers from the start of the project.

Key Benefits:

Predictable imports
Clear provenance

Standard IG Layout

Intent: Keep authors and tools in sync by adopting the HL7 IG Publisher folder schema. When everyone follows the same conventions, onboarding is faster, CI is simpler, and cross-IG contributions become practical.

Key Benefits:

Onboard faster
Simpler CI

Documentation & ADRs

Authoritative documentation lives with the code, and design decisions are captured as Architecture Decision Records (ADRs). When rationale is discoverable in the repository, teams avoid re-litigating past decisions, new members understand 'why' not just 'what', and auditors can trace constraints back to business requirements.

ADR Log

Intent: Make design rationale discoverable and reviewable so that future team members understand why constraints exist, not just what they are. ADRs create an auditable trail of decisions that supports governance and prevents decision debt.

Key Benefits:

Shared memory
Easier governance

Use Cases and Examples

Intent: Organise narrative use cases alongside validated examples

Key Benefits:

Clarity for implementers

FSH Authoring

FHIR Shorthand (FSH) and SUSHI provide a human-readable, version-control-friendly way to author FHIR profiles, extensions, and instances. These patterns help you write FSH that is maintainable, consistent, and reusable across profiles and projects. Good FSH practices reduce diff noise in code review and make refactoring safer.

Aliases and RuleSets

Intent: Centralise constants and reusable rule blocks to reduce duplication, improve consistency, and make refactoring safer. When terminology URLs and common constraints are defined once, changes propagate automatically.

Key Benefits:

Fewer diffs
Safer refactors

Extensions and Slicing

Intent: Constrain responsibly with clear invariants and named slices

Key Benefits:

Predictable matching

Reuse & Co-authoring

When multiple IGs share common profiles, extensions, or terminology, coordination becomes critical. These patterns help you extract shared artifacts into maintainable packages and establish workflows for concurrent editing by distributed teams. Done well, reuse reduces duplication and ensures consistency; done poorly, it creates coupling nightmares.

Shared Modules IG

Intent: Extract cross-cutting profiles, extensions, and terminology into a shared package that can be versioned and released independently. This enables multiple domain IGs to depend on common definitions without copy-paste duplication.

Key Benefits:

Single source of truth

Co-authoring Workflow

Intent: Enable concurrent edits with clear ownership and review

Key Benefits:

Fewer merge conflicts

Staging, Versioning & CI

Reproducible builds are the foundation of reliable IG delivery. These patterns ensure that what works on your laptop works in CI, that consumers can trust version numbers, and that every pull request produces a previewable site. The goal is to eliminate 'works on my machine' problems and give reviewers confidence in what they're approving.

SemVer and Release Channels

Intent: Publish predictable versions and previews so consumers know what to expect. CI builds provide instant feedback, snapshots let integrators test against latest, and releases provide stable baselines for production use.

Key Benefits:

Discoverable artifacts

Local Build Parity

Intent: Ensure the same toolchain runs locally and in CI

Key Benefits:

Fewer "works on my machine" issues

GitHub Actions Pipeline

Intent: Establish standard CI for GitHub-hosted IG repositories that builds, validates, and deploys on every push. Reviewers can see rendered output before merging, and releases are automated from tags.

Key Benefits:

Rapid reviews

GitLab CI Pipeline

Intent: Establish standard CI for GitLab-hosted IG repositories, providing equivalent capabilities to the GitHub Actions pipeline. Essential for organisations using GitLab for private hosting or enterprise features.

Key Benefits:

Parity with GitHub workflows
Works with self-hosted GitLab

Current Version Dependency

Intent: Use the special current version symbol to depend on the latest CI build of an upstream IG, enabling rapid integration testing during active co-development phases.

Key Benefits:

Faster feedback on integration issues
No manual version bumping during co-development
Early detection of breaking changes

Auto-Builder vs Local Builds

Intent: Use the HL7 IG Auto-Builder for rapid feedback during feature development, reserving local builds for release preparation and downstream integration testing.

Key Benefits:

Fast iteration during development
Thorough validation before release
Catches integration issues early

Collaboration & Issues

Well-designed issue templates and PR workflows reduce friction in collaborative IG development. When contributors know what information to provide, triage is faster. When reviewers have checklists, quality is more consistent. These patterns encode team conventions into repository configuration.

Issue Templates

Intent: Capture the right data for changes and defects upfront. Good templates guide contributors to provide context, link to ADRs, and categorise by area — making triage faster and metrics meaningful.

Key Benefits:

Faster triage
Better metrics

PR Templates & CODEOWNERS

Intent: Guided reviews with clear ownership

Key Benefits:

Consistent gates

Quick Reference Table

Pattern	Category	Intent
Canonical URL and Package ID	Repository & Naming	Ensure stable discovery and dependency management across IGs by establishing consistent, predictable identifiers from the start of the project.
Standard IG Layout	Repository & Naming	Keep authors and tools in sync by adopting the HL7 IG Publisher folder schema. When everyone follows the same conventions, onboarding is faster, CI is simpler, and cross-IG contributions become practical.
ADR Log	Documentation & ADRs	Make design rationale discoverable and reviewable so that future team members understand why constraints exist, not just what they are. ADRs create an auditable trail of decisions that supports governance and prevents decision debt.
Use Cases and Examples	Documentation & ADRs	Organise narrative use cases alongside validated examples
Aliases and RuleSets	FSH Authoring	Centralise constants and reusable rule blocks to reduce duplication, improve consistency, and make refactoring safer. When terminology URLs and common constraints are defined once, changes propagate automatically.
Extensions and Slicing	FSH Authoring	Constrain responsibly with clear invariants and named slices
Shared Modules IG	Reuse & Co-authoring	Extract cross-cutting profiles, extensions, and terminology into a shared package that can be versioned and released independently. This enables multiple domain IGs to depend on common definitions without copy-paste duplication.
Co-authoring Workflow	Reuse & Co-authoring	Enable concurrent edits with clear ownership and review
SemVer and Release Channels	Staging, Versioning & CI	Publish predictable versions and previews so consumers know what to expect. CI builds provide instant feedback, snapshots let integrators test against latest, and releases provide stable baselines for production use.
Local Build Parity	Staging, Versioning & CI	Ensure the same toolchain runs locally and in CI
GitHub Actions Pipeline	Staging, Versioning & CI	Establish standard CI for GitHub-hosted IG repositories that builds, validates, and deploys on every push. Reviewers can see rendered output before merging, and releases are automated from tags.
GitLab CI Pipeline	Staging, Versioning & CI	Establish standard CI for GitLab-hosted IG repositories, providing equivalent capabilities to the GitHub Actions pipeline. Essential for organisations using GitLab for private hosting or enterprise features.
Current Version Dependency	Staging, Versioning & CI	Use the special `current` version symbol to depend on the latest CI build of an upstream IG, enabling rapid integration testing during active co-development phases.
Auto-Builder vs Local Builds	Staging, Versioning & CI	Use the HL7 IG Auto-Builder for rapid feedback during feature development, reserving local builds for release preparation and downstream integration testing.
Issue Templates	Collaboration & Issues	Capture the right data for changes and defects upfront. Good templates guide contributors to provide context, link to ADRs, and categorise by area — making triage faster and metrics meaningful.
PR Templates & CODEOWNERS	Collaboration & Issues	Guided reviews with clear ownership