This page is part of the FHIR Specification (v1.8.0: STU 3 Draft). 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 CapabilityStatement, ImplementationGuide, MessageDefinition and OperationDefinition

5.4.4 Resource Content

 

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

5.4.4.1 Terminology Bindings

Path	Definition	Type	Reference
StructureDefinition.status	The lifecycle status of a Value Set or Concept Map.	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.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).isDistinct())
• 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-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.first().slicing.empty())
• 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 (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 (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.
• 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 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 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 fluentpath 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.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),
  "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": "datatype",
     "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": "datatype",
     "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: 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",
     "type": "Patient",
     "baseDefinition": "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",
     "baseDefinition": "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",
     "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": "datatype",
     "type": "Extension",
     "baseDefinition": "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://snomed.info/conceptdomain	SNOMED CT Concept Domain Binding
http://hl7.org/v2	HL7 v2 Mapping
http://hl7.org/v3	RIM Mapping
http://metadata-standards.org/11179/	ISO 11179
http://snomed.info/sct	SNOMED CT Attribute Binding
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://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	In Common
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
context-type	token	resource | datatype | extension	StructureDefinition.contextType
date	date	The structure definition publication date	StructureDefinition.date
derivation	token	specialization | constraint - How relates to base definition	StructureDefinition.derivation
description	string	Text search against the description of the structure definition	StructureDefinition.description
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	External identifiers for the structure definition	StructureDefinition.identifier
jurisdiction	token	Intended jurisdiction for 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	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	Text search against the title of the structure definition	StructureDefinition.title
type	token	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[x] (ValueSet)
version	token	The version identifier of the structure definition	StructureDefinition.version