This page is part of the FHIR Specification (v1.6.0: STU 3 Ballot 4). 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

5.4 Resource StructureDefinition - Content

FHIR Infrastructure Work Group

Maturity Level: 2

Compartments: Not linked to any defined compartments

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 ConceptMap, Conformance, ImplementationGuide and OperationDefinition

5.4.4 Resource Content

 

Alternate definitions: Master Definition (XML, JSON), XML Schema/Schematron (for ) + JSON Schema, ShEx (for Turtle)

5.4.4.1 Terminology Bindings

Path	Definition	Type	Reference
StructureDefinition.status	The lifecycle status of a Value Set or Concept Map.	Required	ConformanceResourceStatus
StructureDefinition.useContext	Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use.	Extensible	Context of Use ValueSet
StructureDefinition.code	Codes for the meaning of the defined structure (SNOMED CT and LOINC codes, as an example).	Example	Structure Definition Codes
StructureDefinition.kind	Defines the type of structure that a definition is describing.	Required	StructureDefinitionKind
StructureDefinition.contextType	How an extension context is interpreted.	Required	ExtensionContext
StructureDefinition.type	Either a resource or a data type, including logical model types	Extensible	FHIRDefinedType
StructureDefinition.derivation	How a type relates to it's baseDefinition.	Required	TypeDerivationRule

5.4.4.2 Constraints

• sdf-1: Element paths must be unique unless the structure is a constraint (expression : derivation = 'constraint' or snapshot.element.select(path).distinct())
• sdf-11: If there's a type, its content must match the path name in the first element of a snapshot (expression : 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.id.trace('ids').isDistinct())
• sdf-17: All element definitions must have unique ids (diff) (expression : differential.element.id.trace('ids').isDistinct())
• sdf-2: On StructureDefinition.mapping: Must have at a name or a uri (or both) (expression on StructureDefinition.mapping: name.exists() or uri.exists())
• 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 and min and max))
• 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() and contextType.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 (url = 'http://hl7.org/fhir/StructureDefinition/'+id))
• sdf-8: On StructureDefinition.snapshot: In any snapshot, all the elements must be in the specified type (expression on StructureDefinition.snapshot: element.first().path = %resource.type and element.tail().all(path.startsWith(%resource.type&'.')))
• 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 the an element without a "." in the path (e.g. the first element) (expression : children().element.first().label.empty() and children().element.first().code.empty() and children().element.first().requirements.empty())

5.4.5 Interpretation Notes:

• A structure is represented as a flat list of elements. The element.path provides the overall structure.
• 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 names of element is changed to include the type instead of '[x]'.
• When using xpath to make 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 xpath constraints refer to elements that offer a choice of types, the statement must use the fully expanded name (including the actual type), not the name ending in "[x]".
• 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, but the rules they describe SHALL be true in any other representation as well
• The condition element is used to assert that a constraint defined on another element affects the allowed cardinality of this element.

5.4.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": (datatype | resource),
  "constrainedType": the type being constrained (if it's a constraint)
  "base": 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": "datatype",
     "base": "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": "datatype",
     "constrainedType": "Quantity",
     "base": "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",
     "base":"http://hl7.org/fhir/StructureDefinition/DomainResource"
   }
   

4. Constraint on a resource (example: DAF Patient - XML , JSON ):
   

   {
     "resourceType": "StructureDefinition",
     "url": "http://hl7.org/fhir/StructureDefinition/daf-patient",
     "name": "U.S. Data Access Framework (DAF) Patient Profile",
     "kind": "resource",
     "constrainedType": "Patient"
     "base":"http://hl7.org/fhir/StructureDefinition/Patient"
   }
   

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

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

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

   {
     "resourceType": "StructureDefinition",
     "url": "http://hl7.org/fhir/StructureDefinition/us-core-race",
     "name": "A category of humans sharing history, origin or nationality",
     "kind": "datatype",
     "constrainedType": "Extension",
     "base": "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": "datatype",
     "constrainedType": "Extension",
     "base": "http://hl7.org/fhir/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.4.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.4.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:

http://ncpdp.org/SCRIPT10_6	Mapping to NCPDP SCRIPT 10.6
http://hl7.org/v2	HL7 v2 Mapping
http://hl7.org/v3	RIM Mapping
http://metadata-standards.org/11179/	ISO 11179
http://nema.org/dicom	DICOM Tag Mapping
http://github.com/MDMI/ReferentIndexContent	MDMI Referent Index
http://ihe.net/xds	XDS metadata equivalent
http://hl7.org/v3/cda	CDA (R2)
http://www.w3.org/ns/prov	W3C PROV
http://loinc.org	LOINC code for the element
http://w3.org/vcard	vCard Mapping
http://snomed.info	SNOMED CT code for the element
http://openehr.org	Open EHR Archetype Mapping

5.4.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 can be useful when

5.4.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	Paths
abstract	token	Whether the structure is abstract	StructureDefinition.abstract
base	uri	Definition that this type is constrained/specialized from	StructureDefinition.baseDefinition
base-path	token	Path that identifies the base element	StructureDefinition.snapshot.element.base.path, StructureDefinition.differential.element.base.path
code	token	A code for the profile	StructureDefinition.code
context	token	A use context assigned to the structure	StructureDefinition.useContext
context-type	token	resource | datatype | extension	StructureDefinition.contextType
date	date	The profile publication date	StructureDefinition.date
derivation	token	specialization | constraint - How relates to base definition	StructureDefinition.derivation
description	string	Text search in the description of the profile	StructureDefinition.description
display	string	Use this name when displaying the value	StructureDefinition.display
experimental	token	If for testing purposes, not real usage	StructureDefinition.experimental
ext-context	string	Where the extension can be used in instances	StructureDefinition.context
identifier	token	The identifier of the profile	StructureDefinition.identifier
kind	token	primitive-type | complex-type | resource | logical	StructureDefinition.kind
name	string	Name of the profile	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 profile	StructureDefinition.publisher
status	token	The current status of the profile	StructureDefinition.status
type	token	Type defined or constrained by this structure	StructureDefinition.type
url	uri	Absolute URL used to reference this StructureDefinition	StructureDefinition.url
valueset	reference	A vocabulary binding reference	StructureDefinition.snapshot.element.binding.valueSet[x] (ValueSet)
version	token	The version identifier of the profile	StructureDefinition.version