StructureDefinition

One-sentence definition: A StructureDefinition is the FHIR resource that formally defines the structure, constraints, and allowed extensions of any other FHIR resource, data type, or extension — it is what validators, tooling, and servers load when they need to know what a conformant resource looks like.

Full Definition

StructureDefinition is a conformance resource in FHIR — a resource about resources. Every base FHIR resource class (Patient, Observation, MedicationRequest) is defined by a StructureDefinition authored by HL7. Every profile that constrains one of those resources is itself a StructureDefinition. Every extension is defined by a StructureDefinition. The resource is FHIR’s universal mechanism for expressing formal structure.

Each StructureDefinition carries an ordered list of ElementDefinition objects — one per element — specifying cardinality, data types, value set bindings, constraints, and Must Support status. This element list exists in two views: the differential records only what changed relative to the base; the snapshot is the fully computed picture with all inherited constraints merged in. Validators consume the snapshot; IG authors write the differential.

A few key attributes identify every StructureDefinition: its canonical url (a globally unique identifier), kind (whether it defines a resource, complex type, primitive type, or logical model), type (the resource or concept being defined), baseDefinition (the URL of what it derives from), and derivation — either constraint for a profile or specialization for a new base type authored by HL7.

For snapshot and differential mechanics, StructureDefinition authoring with FSH/SUSHI, validation workflows, and how profiles chain from base definitions — see the canonical reference → FHIR Profiling.

Context and Usage

Where This Term Appears

StructureDefinition is encountered throughout the FHIR tooling and conformance layer:

• Implementation guides — every IG publishes StructureDefinitions as its primary deliverable; they define the profiles and extensions the IG specifies
• Validators — Inferno, the HL7 FHIR Validator, and Firely SDK all load StructureDefinitions to check resource instances against declared profiles
• Capability statements — servers reference profile URLs (which are StructureDefinition URLs) to declare which profiles they support
• meta.profile — resource instances assert conformance to a profile by including its StructureDefinition URL here
• Tooling errors — “profile not found,” “unknown StructureDefinition,” and “could not resolve canonical” messages all point to a missing or misreferenced StructureDefinition

Common Usage Examples

In conversation: “The validator is throwing errors because it can’t resolve the US Core Patient SD — you need to load the hl7.fhir.us.core package before running validation.”

In documentation: “This profile’s StructureDefinition URL is http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient — include this in meta.profile when asserting conformance.”

In technical contexts — asserting a profile in a resource instance:

{
  "resourceType": "Patient",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
    ]
  }
}

Why StructureDefinitions Exist

FHIR’s base resources define a universal common denominator — useful everywhere, complete nowhere. Every deployment has local requirements: a US system needs race and ethnicity elements; a payer needs plan identifiers; an oncology IG needs tumor staging data. Without a formal mechanism to define and communicate these constraints and extensions, implementers document them in prose that each receiver interprets differently.

StructureDefinition provides a machine-readable, canonical way to declare exactly what a conformant resource looks like in a given context. This makes conformance testable by validators and discoverable by tooling, rather than locked in PDF documentation.

Types of StructureDefinitions

Resource profiles (kind: resource, derivation: constraint) are the type integrators encounter most — a StructureDefinition constraining a base FHIR resource for a specific use case. US Core Patient, AU Core MedicationStatement, and UK Core Condition are all resource profiles.

Extension definitions define a specific FHIR extension. The StructureDefinition specifies the extension’s canonical URL, its value type, and for complex extensions, its child element structure. The URL in an extension’s url attribute is always the canonical URL of its defining StructureDefinition.

Logical models (kind: logical) define structured data without committing to a specific FHIR resource. They model source system data as a precursor to mapping exercises and do not produce FHIR instances.

Base resource and data type definitions (derivation: specialization) are authored exclusively by HL7. They define FHIR’s core types — Patient, Observation, HumanName, CodeableConcept — and are the root of every derivation chain.

Relationship to Other Terms

Related Terms

• Profile — a StructureDefinition with derivation: constraint; “profile” is the conceptual label, StructureDefinition is the technical resource type
• Extension — every FHIR extension has a defining StructureDefinition; the extension’s url is that SD’s canonical URL
• Resource — every FHIR resource class is defined by a base StructureDefinition; resource instances declare profile conformance via meta.profile
• FHIR — StructureDefinition is a core part of FHIR’s conformance infrastructure

Common Misconceptions

Misconception 1: StructureDefinition and Profile Are Synonyms

• Incorrect belief: “StructureDefinition” and “Profile” mean the same thing and can be used interchangeably.
• Reality: A profile is a StructureDefinition with derivation: constraint, but base resource definitions, extension definitions, and logical models are also StructureDefinitions — none of them are profiles. Profile is a subset.
• Why it matters: Tool queries (StructureDefinition?type=Patient) return base definitions and all profiles together. Knowing the distinction prevents confusion when reading tooling output and FHIR package contents.

Misconception 2: You Hand-Author StructureDefinition JSON

• Incorrect belief: Writing FHIR profiles means editing raw StructureDefinition JSON by hand.
• Reality: FHIR Shorthand (FSH) with SUSHI compiles a concise authoring language down to StructureDefinition JSON. Raw JSON is generated output, not the authoring surface — the same relationship as compiled bytecode to source code.
• Why it matters: Teams evaluating IG authoring effort should assess the tooling, not the raw format. FSH has substantially reduced the cost of producing conformance resources.

Why StructureDefinitions Matter

StructureDefinition is the technical foundation of the FHIR conformance ecosystem. Without it there is no machine-readable way to specify what a conformant resource looks like, no basis for automated validation, and no way for tooling to understand the relationship between profiles, base resources, and extensions.

For integrators, StructureDefinitions surface most concretely as validator errors (missing or unresolvable SDs), meta.profile assertions in resource instances, and FHIR package dependencies that must be loaded before validation can run.

Cross-References

Related Glossary Terms

• FHIR — the standard that defines StructureDefinition as a core conformance resource
• Profile — a StructureDefinition that constrains a base resource for a specific use case
• Extension — extensions are defined by StructureDefinitions and referenced by their canonical URL
• Resource — every FHIR resource has a base StructureDefinition that defines its elements

---

Last reviewed: February 18, 2026 Definition authority: HL7 International Content status: Canonical reference