Skip to content

IG Authoring Pattern Language

Welcome to the IG Authoring Pattern Language — a practical guide for teams building HL7® FHIR® Implementation Guides at scale.

Treat IG authoring as software delivery. Keep changes small, validate continuously, and publish frequently to a predictable staging channel.

This pattern language distils lessons learned from dozens of IG projects across government, research, and industry settings. Whether you're starting a greenfield IG or modernising an existing one, these patterns help you avoid common pitfalls and establish sustainable practices.

Target Audience

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

  • IG Lead Owns scope, quality bar, and release train
  • FHIR Engineer Authors profiles, invariants, examples, and pipelines
  • Terminology Steward Owns CodeSystems, ValueSets, ConceptMaps
  • Clinical SME Provides clinical intent and validates usability
  • Implementer Consumes the IG and reports integration feedback
  • QA/Conformance Owns test strategy and cross-IG verification

Common Problems You Face

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

  • Inconsistent naming - Profiles, packages, and files are named inconsistently across modules and releases
  • Fragile repo layout - Authors put content in ad-hoc folders; CI and IG Publisher break
  • Decision debt - Rationale for constraints gets lost; regressions and re-litigation
  • Examples drift - Examples no longer reflect profiles; narrative and instance validation diverge
  • Coupled IGs - Related IGs duplicate artifacts and conflict on versions
  • Release chaos - No harmonised staging, versioning, or CI; local ≠ pipeline

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?

Healthcare interoperability involves unique challenges that generic software patterns don't fully address. While traditional design patterns focus on general software architecture concerns, FHIR implementation patterns address the specific complexities of healthcare data exchange.

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.