This page is part of the FHIR Specification (v1.2.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
• Operations

6.17 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, DecisionSupportServiceModule, ImplementationGuide, ModuleDefinition and OperationDefinition

6.17.4 Resource Content

 

Alternate definitions: Schema/Schematron, Resource Profile (XML, JSON), Questionnaire

6.17.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.constrainedType	Either a resource or a data type.	Required	http://hl7.org/fhir/valueset/defined-typesFHIRDefinedType
StructureDefinition.contextType	How an extension context is interpreted.	Required	ExtensionContext

6.17.4.2 Constraints

• sdf-1: Element paths must be unique unless the structure is a constraint (xpath: exists(f:constrainedType) or (count(f:snapshot/f:element) = count(distinct-values(f:snapshot/f:element/f:path/@value))))
• sdf-10: If the structure is not abstract, or there's a constrained type, then there SHALL be a base (xpath: (f:abstract/@value=true()) or not(exists(f:constrainedType)) or exists(f:base))
• sdf-11: If there's a constrained type, its content must match the path name in the first element of a snapshot (xpath: not(exists(f:constrainedType)) or not(exists(f:snapshot)) or (f:constrainedType/@value = f:snapshot/f:element[1]/f:path/@value))
• sdf-12: element.base cannot appear if there is no base on the structure definition (xpath: f:base or not(exists(f:snapshot/f:element/f:base) or exists(f:differential/f:element/f:base)))
• sdf-2: On StructureDefinition.mapping: Must have at a name or a uri (or both) (xpath on f:StructureDefinition/f:mapping: exists(f:uri) or exists(f:name))
• sdf-3: On StructureDefinition.snapshot: Each element definition in a snapshot must have a formal definition and cardinalities (xpath on f:StructureDefinition/f:snapshot: count(f:element) = count(f:element[exists(f:definition) and exists(f:min) and exists(f:max)]))
• sdf-4: A structure must have a base unless abstract = true (xpath: (f:abstract/@value =true()) or exists(f:base))
• sdf-5: If the structure defines an extension then the structure must have context information (xpath: not(f:constrainedType/@value = 'extension') or (exists(f:context) and exists(f:contextType)))
• sdf-6: A structure must have either a differential, or a snapshot (or both) (xpath: exists(f:snapshot) or exists(f:differential))
• 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 (xpath: exists(f:constrainedType) or f:url/@value=concat('http://hl7.org/fhir/StructureDefinition/', f:id/@value))
• sdf-8: In any snapshot or differential, all the elements except the first have to have a path that starts with the path of the first + "." (xpath: string-join(for $elementName in f:*[self::f:snapshot or self::f:differential]/f:element[position()>1]/f:path/@value return if (starts-with($elementName, concat($elementName/ancestor::f:element/parent::f:*/f:element[1]/f:path/@value, '.'))) then '' else $elementName,'')='')
• 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) (xpath: not(exists(f:snapshot/f:element[not(contains(f:path/@value, '.')) and (f:label or f:code or f:requirements)])) and not(exists(f:differential/f:element[not(contains(f:path/@value, '.')) and (f:label or f:code or f:requirements)])))

6.17.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.

6.17.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.

6.17.5.2 Rules for Constrained Types

When the structure is a constraint (constrainedType is not null), then the following rules apply:

• The structure must nominate a base resource from which it is derived
• The structure definition cannot introduce any new elements or value domains that are not valid in the structure - e.g. the structure must be a true constraint, and anything that meets the description of this structure must also be valid following the description of the base structure
• In practice, this means that:
  • no new paths may be introduced that are not found in the base structure
  • the list of types for an element must be the same or a subset of the list of types for the same element in the base structure
  • The definition can be changed in the derived structure, but it must still be logically consistent with the definition in the base; e.g. the base element may be defined as "Result value" and this structure could define it as "Plasma Cholesterol Test Value", but not "Result status".
  • The cardinality must be a subset of the allowable cardinality in the base structure i.e. the minimum must be >= the base minimum, and the maximum must be <= the base maximum
• Note that because of slicing, there can be more than one element for the same path. For details, see Profiling resources

6.17.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://loinc.org	LOINC code for the element
http://snomed.info	SNOMED CT code for the element
http://hl7.org/v3	RIM mapping
http://hl7.org/v2	HL7 v2 mapping
http://nema.org/dicom	DICOM tag mapping
http://w3.org/vcard	vCard equivalent field
http://ihe.net/xds	XDS metadata equivalent

6.17.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	Structure that this set of constraints applies to	StructureDefinition.base
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 | mapping | extension	StructureDefinition.contextType
date	date	The profile publication date	StructureDefinition.date
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	datatype | 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	Any datatype or resource, including abstract ones	StructureDefinition.constrainedType
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