StructureDefinition — FHIR meta-model

The grammar of FHIR. Every resource, primitive type, complex type, extension and national profile is defined by a StructureDefinition. The engine behind everything that is semantically typed in FHIR.

Purpose of the resource

StructureDefinition defines the shape of every typed thing in FHIR: the resources published by HL7 (Patient, Observation, Bundle…), the primitive types (string, date), the complex types (HumanName, Address, Identifier), custom extensions and national profiles (US Core, FR Core, NL Core…).

A StructureDefinition is composed of elements describing each path (Patient.name.given) with its cardinality, type, terminology binding, FHIRPath constraints, slicing and examples.

Key fields

JSON example

{
  "resourceType": "StructureDefinition",
  "id": "us-core-patient",
  "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient",
  "version": "7.0.0",
  "name": "USCorePatientProfile",
  "title": "US Core Patient Profile",
  "status": "active",
  "publisher": "HL7 International — US Realm",
  "fhirVersion": "5.0.0",
  "kind": "resource",
  "abstract": false,
  "type": "Patient",
  "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Patient",
  "derivation": "constraint",
  "differential": {
    "element": [{
      "id": "Patient.identifier",
      "path": "Patient.identifier",
      "min": 1
    }, {
      "id": "Patient.name",
      "path": "Patient.name",
      "min": 1
    }]
  }
}

Profiles and extensions

• Profile — derivation=constraint restricts a resource (US Core Patient = Patient + identifier 1..*).
• Extension — kind=complex-type + type=Extension adds an ad-hoc field to a resource.
• Logical model — kind=logical defines a conceptual model (FHIR Shorthand, ABMD).
• Slicing — splits a multi-valued field into sub-types (e.g. identifier.use=usual vs official).

Common pitfalls

• No baseDefinition for a profile — the validator does not know what to validate against.
• Snapshot not synchronised — always regenerate the snapshot when the differential changes.
• Poorly discriminated slicing — without a clear discriminator, tools cannot sort.

Related resources

• ImplementationGuide — packages StructureDefinitions.
• StructureMap — transformation.
• ValueSet, CodeSystem.
• CapabilityStatement.
• FHIR R5 hub.