Skip to content

IG Authoring Pattern Language

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.

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

  • 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 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 Categories

Repository & Naming Patterns

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.

Explore Repository & Naming Patterns

Documentation & ADRs Patterns

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.

Explore Documentation & ADRs Patterns

FSH Authoring Patterns

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.

Explore FSH Authoring Patterns

Reuse & Co-authoring Patterns

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.

Explore Reuse & Co-authoring Patterns

Staging, Versioning & CI Patterns

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.

Explore Staging, Versioning & CI Patterns

Collaboration & Issues Patterns

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.

Explore Collaboration & Issues Patterns

Version 0.1.0