FHIR Implementation Guide (IG): Profiles, Extensions, FHIR Shorthand (FSH), SUSHI, Forge, and the HL7 FHIR Validator

A FHIR Implementation Guide (IG) is a formal, computable specification that adapts the base HL7 FHIR standard to a specific clinical, national, or research interoperability use case. Because base FHIR resources follow the “80% rule”—including in core resource schemas only those data elements needed by roughly 80% of healthcare systems globally—real-world deployments (such as US Core, HL7 Da Vinci IGs, or oncology mCODE) rely on FHIR Implementation Guides to define FHIR profiles, FHIR extensions, terminology bindings, and validation rules.

What Is a FHIR Implementation Guide (IG)?

A FHIR Implementation Guide is both a published web specification for human engineers and a machine-readable NPM package (package.tgz) anchored by an HL7 ImplementationGuide conformance resource that bundles all profiles, extensions, value sets, search parameters, and example instances required for a specific interoperability workflow.

Every standards-compliant FHIR Implementation Guide consists of five core conformance artifact layers that a FHIR server or validation engine can load directly into memory:

Conformance Artifact	FHIR Resource Type	Role in an Implementation Guide
IG Manifest & Narrative	ImplementationGuide	Defines the canonical package ID (e.g., hl7.fhir.us.core), FHIR version dependency, package dependencies, and the inventory of all conformance resources and narrative pages.
Profiles & Extensions	StructureDefinition	Defines structural constraints on base resources (Profiles) or defines new custom data elements (Extensions) via snapshot and differential element tables.
Terminology Artifacts	ValueSet, CodeSystem, ConceptMap	Specifies the exact SNOMED CT, LOINC, RxNorm, ICD-10, or local codes permitted in coded fields, along with cross-terminology translations.
API & Behavioral Rules	CapabilityStatement, SearchParameter, OperationDefinition	Declares which RESTful interactions (read, search-type, create), custom search parameters, and extended operations (e.g., $export, $submit) a conformant server or client must support.
Test & Conformance Examples	Any Resource Instance	Provides valid, validator-tested JSON/XML example instances (such as a conformant FHIR Patient or FHIR Condition) proving every profile rule can be satisfied.

How Do FHIR Profiles and Extensions Constrain Base Resources?

Both FHIR profiles and FHIR extensions are authored as StructureDefinition resources: a Profile narrows or constrains an existing base resource without adding new root properties, whereas an Extension introduces a new data element identified by a canonical URI.

1. FHIR Profiles (Constraining via Differential & Snapshot)

A profile sets StructureDefinition.derivation = "constraint" on a target base resource. Each profile contains a differential table (listing only the rules changed from the parent profile) and a generated snapshot table (the complete flattened list of all inherited and constrained elements). Profiling applies five primary constraint mechanisms:

• Cardinality Tightening: Making an optional element mandatory (e.g., constraining Patient.identifier from 0..* to 1..*) or prohibiting an element entirely by setting its maximum cardinality to 0..0. A profile can never loosen a parent’s cardinality (it cannot turn 1..1 into 0..1 or 0..1 into 0..*).
• Must Support (MS) Flags: Setting mustSupport: true on an element. Even if an element has 0..1 minimum cardinality (because a specific patient may not have that data), a Must Support flag legally obligates the sending EHR to populate the element whenever the data exists in its database, and obligates the receiving app to process or display it without error.
• Terminology Binding Strength: Binding a code, Coding, or CodeableConcept element to a ValueSet with one of four strictness levels: required (only codes from the ValueSet are valid), extensible (must use a code from the ValueSet if any concept applies; may use another code only if no concept in the ValueSet covers the clinical meaning), preferred, or example.
• Array Slicing: When a base resource has a repeating 0..* array (such as Observation.component or Patient.identifier), slicing partitions that array into named sub-slices evaluated by a discriminator (e.g., slicing blood pressure Observation.component by code.coding into a required systolic slice with LOINC 8480-6 and a required diastolic slice with LOINC 8462-4).
• FHIRPath Invariants: Expressing cross-element co-occurrence rules using formal FHIRPath boolean expressions (for example, requiring that if Observation.value[x] is absent, Observation.dataAbsentReason must be present).

2. FHIR Extensions (Extending Beyond the 80% Rule)

When a clinical domain or national regulation requires a field that does not exist on the base resource (such as OMB race/ethnicity in the U.S., or tumor TNM staging modifiers in oncology), authors define a StructureDefinition of type = "Extension" with a globally unique canonical URL. In a JSON resource instance, every extension carries "url": "http://..." and either a single typed value[x] property (simple extension, e.g., valueCode or valueQuantity) or an array of child extension objects (complex extension).

How Do You Write FHIR Profiles Using FHIR Shorthand (FSH) and SUSHI?

FHIR Shorthand (FSH) is HL7’s normative domain-specific text language that lets informatics engineers write profiles, extensions, value sets, and examples in concise .fsh files instead of thousands of lines of raw StructureDefinition JSON, using the SUSHI compiler to generate the official FHIR artifacts.

Below is a complete, working FHIR Shorthand (FSH) example that defines a custom clinical trial body weight profile on Observation, constrains its LOINC code and UCUM unit, and creates a conformant example instance:

Alias: $LOINC = http://loinc.org
Alias: $UCUM = http://unitsofmeasure.org

Profile: ClinicalTrialBodyWeight
Parent: Observation
Id: clinical-trial-body-weight
Title: "Clinical Trial Body Weight Observation Profile"
Description: "Constrains FHIR R4 Observation for standardized body weight capture in kilograms."
* status 1..1 MS
* code = $LOINC#29463-7 "Body weight"
* subject 1..1 MS
* subject only Reference(Patient)
* effective[x] 1..1 MS
* effective[x] only dateTime
* value[x] 1..1 MS
* value[x] only Quantity
* valueQuantity.value 1..1 MS
* valueQuantity.system 1..1
* valueQuantity.system = $UCUM
* valueQuantity.code 1..1
* valueQuantity.code = #kg

Instance: ExampleTrialWeight01
InstanceOf: ClinicalTrialBodyWeight
Usage: #example
* status = #final
* subject = Reference(Patient/example-subject-01)
* effectiveDateTime = "2025-10-15T09:30:00Z"
* valueQuantity = 74.5 'kg' "kg"

Authoring, Registry, and Validation Tooling: SUSHI, Forge, Simplifier.net & HL7 FHIR Validator

Modern FHIR Implementation Guide engineering combines four interoperable tools across authoring, package registry management, and automated CI/CD validation:

• SUSHI (“SUSHI Unshortens Short Hand Inputs”): The official open-source command-line compiler (sushi .) maintained by HL7 and MITRE. SUSHI reads sushi-config.yaml and all input/fsh/*.fsh files, resolves external package dependencies from the FHIR package cache (~/.fhir/packages), and outputs valid FHIR JSON resources into fsh-generated/resources/ for the HL7 IG Publisher (_genonce.sh / publisher.jar).
• Firely Forge: A desktop graphical profile editor (developed by Firely for STU3, R4, and R5) that allows clinical data modelers to inspect base resources, click to set cardinalities, configure complex slice discriminators, and author `StructureDefinition` profiles visually without writing code.
• Simplifier.net: A web-based FHIR registry and collaboration platform where project teams host `StructureDefinition` profiles, render interactive tree diagrams of resources, manage project dependencies, and publish versioned FHIR NPM packages.
• HL7 FHIR Validator (validator_cli.jar): The authoritative open-source Java validation engine integrated into the HL7 IG Publisher and enterprise CI/CD pipelines. Running java -jar validator_cli.jar ExampleTrialWeight01.json -version 4.0.1 -ig ./output/package.tgz verifies JSON/XML syntax, structural cardinalities, slice matching, FHIRPath invariants, and terminology code membership against the HL7 terminology server (tx.fhir.org).