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 building FHIR R4 Implementation Guides and terminology artifacts with fast feedback using HL7 build.fhir.org auto-build and the fhir.base.template#current publishing template.

Key Patterns Covered

Thin-Slice Use-Case First - Prevent profile-first paralysis by starting with a thin slice of a real workflow demonstrable end-to-end.
Executable Contract Backlog - Make requirements testable using conformance statements + examples + tests, tracked to issues.
Decision Log (ADR) with Reversibility - Capture key decisions as lightweight ADRs with explicit revisit triggers.
Two-Speed Workgroups - Separate a small delivery core from a broader review ring to balance velocity and legitimacy.
Definition-of-Done per Artifact - Define Done for each artifact type to prevent “nearly done” outputs.
FSH-First, Repo-First Authoring - Use FSH + Git for diffable, distributed authoring; avoid hand-editing JSON/XML.
Package-First IG Layout - Treat the IG as a versioned package with stable canonical + dependencies.
HL7 Build Preview Pipeline (base template) - Use HL7 auto-build to generate previews for every push using fhir.base.template#current.
Three-Layer Terminology Model - Separate CodeSystem/ValueSet/ConceptMap roles to reduce semantic drift.
Terminology as a Service (TaaS) Gate - Run $expand/$validate-code/$lookup in CI against a pinned terminology environment.
Terminology Release Train - Coordinate terminology change with IG releases using deprecation windows and diffs.

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:

Kickoff - Establish shared, testable direction in days—not months—by converting scope, risks, and success criteria into executable artifacts and decision logs.
Governance - Create workgroups that are small enough to decide and broad enough to be legitimate, with a cadence aligned to shipping increments.
Authoring Stack - Use a software-engineering-grade authoring stack (FSH + CI + packages) and HL7 auto-build previews with the neutral base template.
Terminology - Make terminology an explicit product with governance, distribution, and tests—so meanings don’t drift across implementations.
Profiling - Profile only as much as needed; bound complexity; ensure constraints are executable and justified.
Testing & Verification - Build a verification pipeline that continuously checks conformance across validators, servers, SDKs, and test platforms.
Release & Operations - Release with compatibility guarantees, publish packages, and operate with a predictable change process.

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

Kickoff

Establish shared, testable direction in days—not months—by converting scope, risks, and success criteria into executable artifacts and decision logs.

Thin-Slice Use-Case First

Intent: Prevent profile-first paralysis by starting with a thin slice of a real workflow demonstrable end-to-end.

Key Benefits:

Working skeleton in days
Hidden assumptions surface early
Scope stays honest

Executable Contract Backlog

Intent: Make requirements testable using conformance statements + examples + tests, tracked to issues.

Key Benefits:

Less rework
Automated gating
Vendor alignment

Decision Log (ADR) with Reversibility

Intent: Capture key decisions as lightweight ADRs with explicit revisit triggers.

Key Benefits:

Fast decisions with rationale
Avoid re-litigation

Governance

Create workgroups that are small enough to decide and broad enough to be legitimate, with a cadence aligned to shipping increments.

Two-Speed Workgroups

Intent: Separate a small delivery core from a broader review ring to balance velocity and legitimacy.

Key Benefits:

Decisions stay fast
Reviews predictable

Definition-of-Done per Artifact

Intent: Define Done for each artifact type to prevent “nearly done” outputs.

Key Benefits:

Predictable throughput
Fewer regressions

Authoring Stack

Use a software-engineering-grade authoring stack (FSH + CI + packages) and HL7 auto-build previews with the neutral base template.

FSH-First, Repo-First Authoring

Intent: Use FSH + Git for diffable, distributed authoring; avoid hand-editing JSON/XML.

Key Benefits:

Reviewable diffs
Automation-friendly

Package-First IG Layout

Intent: Treat the IG as a versioned package with stable canonical + dependencies.

Key Benefits:

Reliable validation
Composable dependencies

HL7 Build Preview Pipeline (base template)

Intent: Use HL7 auto-build to generate previews for every push using fhir.base.template#current.

Key Benefits:

Immediate preview URLs
Shared debugging logs

Terminology

Make terminology an explicit product with governance, distribution, and tests—so meanings don’t drift across implementations.

Three-Layer Terminology Model

Intent: Separate CodeSystem/ValueSet/ConceptMap roles to reduce semantic drift.

Key Benefits:

Semantic stability
Better mapping

Terminology as a Service (TaaS) Gate

Intent: Run $expand/$validate-code/$lookup in CI against a pinned terminology environment.

Key Benefits:

Catches drift early
Cross-product consistency

Terminology Release Train

Intent: Coordinate terminology change with IG releases using deprecation windows and diffs.

Key Benefits:

Predictable adoption
Fewer breaking changes

Profiling

Profile only as much as needed; bound complexity; ensure constraints are executable and justified.

Profile Minimalism with Justification

Intent: Every constraint must have a reason, an example, and a test; keep profiles lean.

Key Benefits:

Easier adoption
Less validator friction

Slice Explosion Control

Intent: Bound slicing complexity using budgets, conventions, and review gates.

Key Benefits:

Avoid brittle profiles
Better tooling performance

Example-Driven Profiling

Intent: Use examples as first-class design artifacts; every profile/value set validates and renders.

Key Benefits:

Regression tests
Usable IG

Testing & Verification

Build a verification pipeline that continuously checks conformance across validators, servers, SDKs, and test platforms.

Validator Gate in CI

Intent: Run IG Publisher validation as a hard gate on every PR.

Key Benefits:

Prevents broken packages
Catches FHIRPath issues

Cross-Product Interop Matrix

Intent: Test across validators/servers/SDKs continuously to catch ecosystem differences early.

Key Benefits:

Avoid vendor-specific success
Build confidence

TestScript / Inferno / Touchstone Alignment

Intent: Write portable conformance tests using TestScript/TestPlan conventions and execute on common platforms.

Key Benefits:

Reusable across vendors
Supports certification

Release & Operations

Release with compatibility guarantees, publish packages, and operate with a predictable change process.

Release Trains + Compatibility Contracts

Intent: Ship on predictable trains with semver, published packages, and compatibility promises.

Key Benefits:

Plannable upgrades
Reduced surprises

Change Impact Check & Diff Reports

Intent: Generate diffs and impact reports when artifacts change; validate downstream; publish migration notes.

Key Benefits:

Fewer regressions
Transparency

Quick Reference Table

Pattern	Category	Intent
Thin-Slice Use-Case First	Kickoff	Prevent profile-first paralysis by starting with a thin slice of a real workflow demonstrable end-to-end.
Executable Contract Backlog	Kickoff	Make requirements testable using conformance statements + examples + tests, tracked to issues.
Decision Log (ADR) with Reversibility	Kickoff	Capture key decisions as lightweight ADRs with explicit revisit triggers.
Two-Speed Workgroups	Governance	Separate a small delivery core from a broader review ring to balance velocity and legitimacy.
Definition-of-Done per Artifact	Governance	Define Done for each artifact type to prevent “nearly done” outputs.
FSH-First, Repo-First Authoring	Authoring Stack	Use FSH + Git for diffable, distributed authoring; avoid hand-editing JSON/XML.
Package-First IG Layout	Authoring Stack	Treat the IG as a versioned package with stable canonical + dependencies.
HL7 Build Preview Pipeline (base template)	Authoring Stack	Use HL7 auto-build to generate previews for every push using fhir.base.template#current.
Three-Layer Terminology Model	Terminology	Separate CodeSystem/ValueSet/ConceptMap roles to reduce semantic drift.
Terminology as a Service (TaaS) Gate	Terminology	Run $expand/$validate-code/$lookup in CI against a pinned terminology environment.
Terminology Release Train	Terminology	Coordinate terminology change with IG releases using deprecation windows and diffs.
Profile Minimalism with Justification	Profiling	Every constraint must have a reason, an example, and a test; keep profiles lean.
Slice Explosion Control	Profiling	Bound slicing complexity using budgets, conventions, and review gates.
Example-Driven Profiling	Profiling	Use examples as first-class design artifacts; every profile/value set validates and renders.
Validator Gate in CI	Testing & Verification	Run IG Publisher validation as a hard gate on every PR.
Cross-Product Interop Matrix	Testing & Verification	Test across validators/servers/SDKs continuously to catch ecosystem differences early.
TestScript / Inferno / Touchstone Alignment	Testing & Verification	Write portable conformance tests using TestScript/TestPlan conventions and execute on common platforms.
Release Trains + Compatibility Contracts	Release & Operations	Ship on predictable trains with semver, published packages, and compatibility promises.
Change Impact Check & Diff Reports	Release & Operations	Generate diffs and impact reports when artifacts change; validate downstream; publish migration notes.