This page is part of the FHIR Specification (v3.3.0: R4 Ballot 2). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

• Content
• Examples
• Detailed Descriptions
• Mappings
• Profiles & Extensions
• Operations
• R2 Conversions

5.3 Resource StructureDefinition - Content

FHIR Infrastructure Work Group

Maturity Level: 5

Normative

Compartments: Not linked to any defined compartments

Normative Candidate Note: This page is candidate normative content for R4 in the Conformance Package. Once normative, it will lose it's Maturity Level, and breaking changes will no longer be made.

A definition of a FHIR structure. This resource is used to describe the underlying resources, data types defined in FHIR, and also for describing extensions and constraints on resources and data types.

This resource is referenced by CapabilityStatement, GraphDefinition, ImplementationGuide, MessageDefinition, OperationDefinition, StructureMap and TerminologyCapabilities

5.3.4 Resource Content

 

Alternate definitions: Master Definition XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) + see the extensions & the dependency analysis

5.3.4.1 Terminology Bindings

Path	Definition	Type	Reference
StructureDefinition.status	The lifecycle status of an artifact.	Required	PublicationStatus
StructureDefinition.jurisdiction	Countries and regions within which this artifact is targeted for use	Extensible	Jurisdiction ValueSet
StructureDefinition.keyword	Codes for the meaning of the defined structure (SNOMED CT and LOINC codes, as an example).	Example	Structure Definition Codes
StructureDefinition.fhirVersion	All published FHIR Versions	Required	All Published FHIR versions
StructureDefinition.kind	Defines the type of structure that a definition is describing.	Required	StructureDefinitionKind
StructureDefinition.context.type	How an extension context is interpreted.	Required	ExtensionContextType
StructureDefinition.type	Either a resource or a data type, including logical model types	Extensible	FHIRDefinedType
StructureDefinition.derivation	How a type relates to its baseDefinition.	Required	TypeDerivationRule

5.3.4.2 Constraints

• sdf-1: Element paths must be unique unless the structure is a constraint (expression : derivation = 'constraint' or snapshot.element.select(path).isDistinct())
• sdf-10: On StructureDefinition.snapshot.element: provide either a binding reference or a description (or both) (expression on StructureDefinition.snapshot.element: binding.empty() or binding.valueSet.exists() or binding.description.exists())
• sdf-11: If there's a type, its content must match the path name in the first element of a snapshot (expression : kind != 'logical' implies snapshot.empty() or snapshot.element.first().path = type)
• sdf-12: element.base cannot appear if there is no base on the structure definition (expression : snapshot.exists() implies (snapshot.element.base.exists() = baseDefinition.exists()))
• sdf-14: All element definitions must have an id (expression : snapshot.element.all(id.exists()) and differential.element.all(id.exists()))
• sdf-15: On StructureDefinition.snapshot: The first element in a snapshot has no type (expression on StructureDefinition.snapshot: element.first().type.empty())
• sdf-15a: On StructureDefinition.differential: If the first element in a differential has no "." in the path, it has no type (expression on StructureDefinition.differential: element.first().path.contains('.').not() implies element.first().type.empty())
• sdf-16: All element definitions must have unique ids (snapshot) (expression : snapshot.element.all(id) and snapshot.element.id.trace('ids').isDistinct())
• sdf-17: All element definitions must have unique ids (diff) (expression : differential.element.all(id) and differential.element.id.trace('ids').isDistinct())
• sdf-18: Context Invariants can only be used for extensions (expression : contextInvariant.exists() implies type = 'Extension')
• sdf-19: Custom types can only be used in logical models (expression : kind = 'logical' or (differential.element.type.code.all(hasValue() implies matches('^[a-zA-Z0-9]+$')) and snapshot.element.type.code.all(hasValue() implies matches('^[a-zA-Z0-9]+$'))))
• sdf-2: On StructureDefinition.mapping: Must have at least a name or a uri (or both) (expression on StructureDefinition.mapping: name.exists() or uri.exists())
• sdf-20: On StructureDefinition.differential: No slicing on the root element (expression on StructureDefinition.differential: element.where(path.contains('.').not()).slicing.empty())
• sdf-21: Default values can only be specified on logical models (expression : (snapshot.element.defaultValue.exists() or differential.element.defaultValue.exists()) implies ((kind = 'logical') and (derivation = 'specialization')))
• sdf-3: On StructureDefinition.snapshot: Each element definition in a snapshot must have a formal definition and cardinalities (expression on StructureDefinition.snapshot: element.all(definition.exists() and min.exists() and max.exists()))
• sdf-4: If the structure is not abstract, then there SHALL be a baseDefinition (expression : abstract = true or baseDefinition.exists())
• sdf-5: If the structure defines an extension then the structure must have context information (expression : type != 'Extension' or derivation = 'specialization' or (context.exists()))
• sdf-6: A structure must have either a differential, or a snapshot (or both) (expression : snapshot.exists() or differential.exists())
• sdf-7: If the structure describes a base Resource or Type, the URL has to start with "http://hl7.org/fhir/StructureDefinition/" and the tail must match the id (expression : (derivation = 'constraint') or (kind = 'logical') or (url = 'http://hl7.org/fhir/StructureDefinition/'+id))
• sdf-8: On StructureDefinition.snapshot: In any snapshot, all the elements must be in the specified type, and must have a base definition (expression on StructureDefinition.snapshot: element.first().path = %resource.type and element.tail().all(path.startsWith(%resource.type&'.')) and element.all(base.exists()))
• sdf-8a: On StructureDefinition.differential: In any differential, all the elements must be in the specified type (expression on StructureDefinition.differential: element.first().path.startsWith(%resource.type) and element.tail().all(path.startsWith(%resource.type&'.')))
• sdf-9: In any snapshot or differential, no label, code or requirements on an element without a "." in the path (e.g. the first element) (expression : children().element.where(path.contains('.').not()).label.empty() and children().element.where(path.contains('.').not()).code.empty() and children().element.where(path.contains('.').not()).requirements.empty())

5.3.5 Interpretation Notes:

• A structure is represented as a flat list of elements. The element.path provides the overall structure.
• Differentials in constraints need only specify elements that they are making rules about. Other elements can be inferred as defined in the base resource
• Elements specified in the differential (and all elements in the snapshot) must be ordered as such:
  • Elements from the baseDefinition appear before new elements in a specialization profile
  • Elements must be in the same order as the baseDefinition, and child elements appear in depth-first order.
  • Unsliced descendants of sliced elements appear before slices
• element.short, element.formal, element.comments and element.mapping provide the specific definition for the field in a specific context.
• element.type is used to specify which types may be used for this element. If there is more than one type, the element offers a choice of types and must have a name that terminates in "[x]". When profiling a resource and only one type is specified, the name of the element is changed to include the type instead of '[x]'.
• When using XPath to define constraints about the relationship between the contents of the narrative and the contents of the data elements, the element against which the rule is expressed is the one against which the error or warning will be reported by a validator.
• When expression constraints are placed on elements that offer a choice of types, the expression has to select the type to which it applies using the FHIRPath is operator.
• For XPath constraints, the prefix "f" should be used for "http://hl7.org/fhir", and "h" for "http://www.w3.org/1999/xhtml". XPath constraints are written against the XML representation
• The condition element is used to assert that a constraint defined on another element affects the allowed cardinality of this element.

5.3.5.1 Different Uses for StructureDefinition

The base structure definition is used in a number of different ways to support the FHIR specification. The various uses of the StructureDefinition are controlled by the elements kind, constrainedType, base, and url, using this basic pattern:

{
  "url": the identity of this structure definition,
  "kind": (primitive-type | complex-type | resource | logical),
  "type": the type being constrained (if it's a constraint)
  "baseDefinition": the structure definition from which this is derived
}

This list shows a number of examples, with links to real examples for each:

1. Base definition of a data type (example: Quantity - XML, JSON):
   

   {
     "resourceType": "StructureDefinition",
     "url": "http://hl7.org/fhir/StructureDefinition/Quantity",
     "name": "Quantity",
     "kind": "complex-type",
     "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Element"
   }
   

2. A constrained data type (example: Money - XML, JSON):
   

   {
     "resourceType": "StructureDefinition",
     "url": "http://hl7.org/fhir/StructureDefinition/Money",
     "name": "Money",
     "kind": "complex-type",
     "type": "Quantity",
     "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Quantity"
   }
   

3. Base definition of a resource (example: Patient - XML, JSON):
   

   {
     "resourceType": "StructureDefinition",
     "url": "http://hl7.org/fhir/StructureDefinition/Patient",
     "name": "Patient",
     "kind": "resource",
     "baseDefinition": "http://hl7.org/fhir/StructureDefinition/DomainResource"
   }
   

4. Constraint on a resource (example: Clinical Document Profile for Composition - XML, JSON):
   

   {
     "resourceType": "StructureDefinition",
     "url": "http://hl7.org/fhir/StructureDefinition/clinicaldocument",
     "name": "Clinical Document Profile for Composition",
     "kind": "resource",
     "type": "Composition",
     "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Composition"
   }
   

5. Base Extension (a standard data type) (example: Extension - XML, JSON):
   

   {
     "resourceType": "StructureDefinition",
     "url": "http://hl7.org/fhir/StructureDefinition/Extension",
     "name": "Extension",
     "kind": "datatype",
     "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Element"
   }
   

6. A defined Extension (example: Extension Data Absent Reason - XML, JSON):
   

   {
     "resourceType": "StructureDefinition",
     "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
     "name": "Data Absent Reason",
     "kind": "complex-type",
     "type": "Extension",
     "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Extension"
   }
   

7. A constraint on a defined extension (no examples currently defined):
   

   {
     "resourceType": "StructureDefinition",
     "url": "http://example.org/fhir/StructureDefinition/race",
     "name": "Race codes used by institution (a subset of meaningful use codes)",
     "kind": "complex-type",
     "type": "Extension",
     "baseDefinition": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race"
   }
   

On this list, structure definitions of type 1, 3, and 5 can only be defined by the FHIR specification itself. The other kinds of structure definitions are (or may be) created by the specification but can also be defined by other implementers.

5.3.5.2 Rules for Constrained Types

When the structure is a constraint (constrainedType is not null), see Extending and Restricting Resources for the rules that apply.

5.3.5.3 Common Mapping Targets

Structures are able to map elements to concepts in other definition systems. Generally, these are used to map the elements to local implementation models, data paths, and concepts. However they are also used to map to other standards and published terminologies. These are the standard URIs used for common targets of the mapping:

Name	Details
Logical Mapping	Formal URL: http://hl7.org/fhir/logical
ClinicalTrials.gov Mapping	Formal URL: http://clinicaltrials.gov
Workflow Pattern	Formal URL: http://hl7.org/fhir/workflow
CDISC Define XML 2.0 metadata standard	Formal URL: http://www.cdisc.org/define-xml
Mapping to NCPDP SCRIPT 10.6	Formal URL: http://ncpdp.org/SCRIPT10_6
FiveWs Pattern	Formal URL: http://hl7.org/fhir/fivews
IHE Structured Data Capture	Formal URL: http://siframework.org/ihe-sdc-profile
Canadian Dental Association eclaims standard	Formal URL: http://www.cda-adc.ca/en/services/cdanet/
SNOMED CT Concept Domain Binding	Formal URL: http://snomed.info/conceptdomain Concept domain bindings link a resource or an element to a set of SNOMED CT concepts that represent the intended semantics of the instances (whether or not SNOMED CT is used to encode that data element). This set of concepts is represented using a SNOMED CT expression constraint. Note that the 'Concept domain binding' may be a superset of the 'value set binding'. These bindings help to support: Quality checking FHIR resources by ensuring that (a) the intended semantics of the instances matches the valid range of the corresponding SNOMED CT attribute, and (b) the intended value set is appropriate for the intended semantics of the instances Semantic checking of data instances by helping to detect potential inconsistencies caused by overlap between the semantics incorporated in two concept domains
R3-ReferalRequest Mapping	Formal URL: http://hl7.org/fhir/rr
HL7 v2 Mapping	Formal URL: http://hl7.org/v2
RIM Mapping	Formal URL: http://hl7.org/v3
ISO 11179	Formal URL: http://metadata-standards.org/11179/ These mappings are included to indicate where properties of the data elements defined by the FHIR specification relate to similar fields in the ISO 11179 specification.
SNOMED CT Attribute Binding	Formal URL: http://snomed.info/sct Attribute bindings link coded data elements in FHIR resources to a corresponding attribute in the SNOMED CT concept model. These bindings help to support: clarifying the intended meaning of the data element Quality checking the alignment between FHIR resource design and any coresponding SNOMED CT concept model Composition and decomposition of data instances by indicating the SNOMED CT concept model attribute whose value may be used to decompose a precoordinated concept into this data element
Quality Improvement Domain Analysis Model	Formal URL: http://hl7.org/qidam
DICOM Tag Mapping	Formal URL: http://nema.org/dicom
MDMI Referent Index	Formal URL: http://github.com/MDMI/ReferentIndexContent
V3 Pharmacy Dispense RMIM	Formal URL: http://www.hl7.org/v3/PORX_RM020070UV
XDS metadata equivalent	Formal URL: http://ihe.net/xds
CAP Code	Formal URL: http://cap.org/ecc
CDA (R2)	Formal URL: http://hl7.org/v3/cda
Quality Improvement and Clinical Knowledge (QUICK)	Formal URL: http://siframework.org/cqf
Canadian Pharmacy Associaiton eclaims standard	Formal URL: http://www.pharmacists.ca/
UDI Mapping	Formal URL: http://fda.gov/UDI UDI is a unique numeric or alphanumeric code that consists of two parts: (1) a device identifier (DI), a mandatory, fixed portion of a UDI that identifies the labeler and the specific version or model of a device, and (2) a production identifier (PI), a conditional, variable portion of a UDI that identifies one or more of the following when included on the label of a device: (2a) the lot or batch number within which a device was manufactured; (2b) the serial number of a specific device; (2c) the expiration date of a specific device; (2d) the date a specific device was manufactured; (2e) the distinct identification code required by §1271.290(c) for a human cell, tissue, or cellular and tissue-based product (HCT/P) regulated as a device.
Quality Data Model	Formal URL: http://www.healthit.gov/quality-data-model
FHIR AuditEvent	Formal URL: http://hl7.org/fhir/auditevent
IHE Data Element Exchange (DEX)	Formal URL: http://ihe.net/data-element-exchange
W3C PROV	Formal URL: http://www.w3.org/ns/prov The provenance resource is based on known practices in the HL7 implementation space, particularly those found in the v2 EVN segment, the v3 ControlAct Wrapper, the CDA header, and IHE ATNA. The conceptual model underlying the design is the W3C provenance Specification . Though the content and format of the resource is designed to meet specific requirements for FHIR, all the parts of the resource are formally mapped to the PROV-O specification, and FHIR resources can be transformed to their W3C PROV equivalent.
Ontological RIM Mapping	Formal URL: http://hl7.org/orim
LOINC code for the element	Formal URL: http://loinc.org
vCard Mapping	Formal URL: http://w3.org/vcard
Open EHR Archetype Mapping	Formal URL: http://openehr.org
ServD	Formal URL: http://www.omg.org/spec/ServD/1.0/
FHIR Provenance	Formal URL: http://hl7.org/fhir/provenance
iCalendar	Formal URL: http://ietf.org/rfc/2445

5.3.5.4 Logical Models

StructureDefinitions are used to define the basic structures of FHIR: data types, resources, extensions, and profiles. The same definition structure can also be used to define any arbitrary structures that are a directed acyclic graph with typed nodes, where the primitive types are those defined by the FHIR specification.

This technique has many uses:

• Describing any arbitrary content model
• Describing existing HL7 content models (e.g. v2, CDA) using FHIR
• Describing common design patterns used in FHIR
• Defining a content model to support the mapping language

5.3.6 Search Parameters

Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

Name	Type	Description	Expression	In Common
abstract	token	Whether the structure is abstract	StructureDefinition.abstract
base	reference	Definition that this type is constrained/specialized from	StructureDefinition.baseDefinition (StructureDefinition)
base-path	token	Path that identifies the base element	StructureDefinition.snapshot.element.base.path | StructureDefinition.differential.element.base.path
date	date	The structure definition publication date	StructureDefinition.date
derivation	token	specialization | constraint - How relates to base definition	StructureDefinition.derivation
description	string	The description of the structure definition	StructureDefinition.description
experimental	token	For testing purposes, not real usage	StructureDefinition.experimental
ext-context	token	The system is the URL for the context-type: e.g. http://hl7.org/fhir/extension-context-type#element|CodeableConcept.text	StructureDefinition.context
identifier	token	External identifier for the structure definition	StructureDefinition.identifier
jurisdiction	token	Intended jurisdiction for the structure definition	StructureDefinition.jurisdiction
keyword	token	A code for the profile	StructureDefinition.keyword
kind	token	primitive-type | complex-type | resource | logical	StructureDefinition.kind
name	string	Computationally friendly name of the structure definition	StructureDefinition.name
path	token	A path that is constrained in the profile	StructureDefinition.snapshot.element.path | StructureDefinition.differential.element.path
publisher	string	Name of the publisher of the structure definition	StructureDefinition.publisher
status	token	The current status of the structure definition	StructureDefinition.status
title	string	The human-friendly name of the structure definition	StructureDefinition.title
type	uri	Type defined or constrained by this structure	StructureDefinition.type
url	uri	The uri that identifies the structure definition	StructureDefinition.url
valueset	reference	A vocabulary binding reference	StructureDefinition.snapshot.element.binding.valueSet (ValueSet)
version	token	The business version of the structure definition	StructureDefinition.version