Skip to content

FHIR Authoring Pattern Language

Treat IG authoring as software delivery: build a thin slice, validate continuously, and ship increments. The IG is an executable contract packaged for tooling and implementers.

Target Audience

This documentation is designed for healthcare technology professionals who face complex interoperability challenges:

  • IG Lead Owns scope, decisions, and release train.
  • Terminology Steward Owns CodeSystems/ValueSets/ConceptMaps and terminology server behavior.
  • FHIR Engineer Authors profiles, examples, tests, and CI.
  • Clinical SME Provides clinical intent and usability feedback.
  • Vendor Implementer Builds implementations and provides interoperability feedback.
  • QA / Conformance Owns test strategy and cross-product verification.

Common Problems You Face

If you're working in healthcare IT, you likely encounter these recurring challenges:

  • Slow IG development - Friction in authoring and review causes long feedback loops.
  • Terminology drift - ValueSet expansions and mappings change silently across environments.
  • Interop surprises - Works locally but fails in partner products and validators.
  • Unclear ownership - Decisions stall and constraints conflict.

Pattern Languages for Better Communication

Pattern languages are a proven approach to improving technical communication by organizing stereotypical solutions to recurring problems. Originally developed by architect Christopher Alexander for urban planning and building design, pattern languages have been successfully adapted to software engineering through influential works like the Gang of Four's "Design Patterns."

Why Pattern Languages Work

Pattern languages help teams by:

  • Establishing shared vocabulary - Common names for complex architectural concepts
  • Capturing proven solutions - Documenting what works in real-world implementations
  • Revealing relationships - Showing how individual patterns combine to solve larger problems
  • Accelerating decision-making - Providing tested approaches rather than starting from scratch
  • Facilitating knowledge transfer - Enabling experienced architects to share insights systematically

Why Patterns for FHIR?

Creating high-quality FHIR Implementation Guides (IGs) isn’t just “writing documentation”. An IG is an executable contract: it contains computable profiles, terminology artifacts, examples, invariants, and testable conformance expectations.

That makes IG authoring closer to software delivery than to traditional standards writing. FHIR authoring patterns capture practical, repeatable ways to ship IGs with fast feedback and fewer downstream surprises.

Key motivations:

  • Treat IG authoring as delivery — work in thin slices, keep the IG always buildable, and publish frequently instead of “big bang” releases.
  • Continuous validation is non-negotiable — SUSHI, the IG Publisher, terminology validation, and example validation must run in CI so issues are caught immediately.
  • Terminology is part of the product — CodeSystems, ValueSets, ConceptMaps, versioning, and governance workflows need explicit patterns, not ad‑hoc decisions.
  • Profile layering needs discipline — design specialization hierarchies and reuse boundaries to avoid brittle inheritance and ecosystem fragmentation.
  • Multiple stakeholders, one artifact — clinical SMEs, terminology stewards, engineers, and implementers all edit/consume the same IG; patterns reduce friction and ambiguity.
  • Tooling and infrastructure shape success — HL7’s build.fhir.org pipelines, templates, and publishing conventions strongly influence what “good” looks like in practice.

The goal of this book is to make authoring predictable: faster iteration, cleaner releases, and IGs that implementers can trust.

Getting Started

We recommend starting with the foundational concepts and building up:

  1. Forces Analysis - Understanding the specific problems, tensions, and context that drive the need for patterns
  2. Pattern Catalog - Comprehensive overview of all patterns, their philosophy, organization, and detailed descriptions

Pattern Structure

Each pattern in this collection follows a consistent structure derived from classical pattern literature:

  1. Intent - What specific problem does this pattern solve?
  2. Forces - What tensions and constraints drive the need for this pattern?
  3. Structure - Class diagrams showing the pattern's components
  4. Behavior - Sequence diagrams showing how the pattern works at runtime
  5. Implementation - Concrete guidance for implementing the pattern with FHIR
  6. Related Patterns - How this pattern combines with others in the healthcare context

Pattern-Based Approach

These patterns follow established software design pattern principles, making them familiar to developers while addressing healthcare-specific challenges like consent management, audit requirements, and multi-modal data integration.

Implementation Flexibility

These patterns are architectural templates, not rigid implementations. Adapt them to your specific technology stack, organizational constraints, and regulatory requirements.