This page is part of the FHIR Specification (v1.0.2: DSTU 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: R5R4BR4R3R2
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.
6.17.1 Scope and Usage
The StructureDefinition resource describes a structure - a set of data element definitions, and their associated rules of usage.
These structure definitions are used to describe both the content defined in the FHIR specification
itself - Resources, data types, the underlying infrastructural types, and also are used to describe how
these structures are used in implementations.
This allows the definitions of the structures to be shared and published through
repositories of structure definitions, compared with each other, and used as the basis
for code, report and UI generation.
StructureDefinitions are used by Conformance instances for specifying how resources are used
StructureDefinitions use Value Sets to specify the content of coded elements
StructureDefinitions define concrete elements and structures for use with FHIR alone and that have defined wire representations (XML, JSON, etc.).
This is distinct from DataElement which defines abstract elements that might appear anywhere - FHIR,
questionnaire questions, CDA , HL7 v2 , X12, OpenEHR, a proprietary database, etc. Data elements may map to FHIR resources, data types and/or extensions
but do not have any defined wire format of their own.
6.17.3 Background and Context
Implementers should be familiar with the
background and concepts described in Profiling FHIR
before working with this resource.
6.17.3.1 Metadata
The StructureDefinition resource has a set of metadata that is mostly shared with the Value Set,
Conformance and other infrastructure resources. The metadata describes the structure, and helps
find the structure when registered in profile repositories.
url
The identifier that is used to identify this structure when it is referenced in a specification, model, design or an instance. This URL is where the structure can be accessed
identifier
Other identifiers that are used to identify this structure
version
The identifier that is used to identify this version of the structure when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the structure author manually and the value should be a timestamp.
Note that there may be multiple resource versions of the structure that have this same identifier. The resource will have updates that create new versions for technical reasons, whereas the stated version number needs to be under the author's control
name
A free text natural language name identifying the structure
publisher
Details of the individual or organization who accepts responsibility for publishing the structure. This helps establish the "authority/credibility" of the structure.
telecom
Contact details to assist a user in finding and communicating with the publisher
description
A free text natural language description of the structure and its use
requirements
The Scope and Usage that this structure was created to meet
code
A set of terms from external terminologies that may be used to assist with indexing and searching of profiles
status
The status of the structure allows filtering of profiles that are appropriate for use vs. not. See the Status Codes
experimental
This structure was authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usage
date
The date this version of the structure was published
fhirVersion
The version of the FHIR specification on which this structure is based. It is not necessary to specify the version, as most profiles are valid across multiple versions, and the validity of a structure against a particular version of FHIR can easily be checked by tooling.
type
todo
contextType
todo
context
todo
Notes:
The name of the structure is not required to be globally unique, but the name should have some scoping information (e.g. Acme Inc. (USA), Allergy List)
Multiple codes may be assigned to the structure. These may either describe the structure, the focus of the structure or both. They are solely to help find the structure by searching for structured concepts
The 3 status codes (draft, active, and retired) are the codes that are relevant to structure consumers. Authors may wish to use the authoring-status extension to track the life cycle of a structure as it is prepared
Structural Definition If there's a constrained type, its content must match the path name in the first element of a snapshot If the structure defines an extension then the structure must have context information element.base cannot appear if there is no base on the structure definition A structure must have a base unless abstract = true element.base must appear if there is a base on the structure definition 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 A structure must have either a differential, or a snapshot (or both) Element paths must be unique unless the structure is a constraint In any snapshot or differential, all the elements except the first have to have a path that starts with the path of the first + "." In any snapshot or differential, no label, code or requirements on the an element without a "." in the path (e.g. the first element) If the structure is not abstract, or there's a constrained type, then there SHALL be a base
Structural Definition If there's a constrained type, its content must match the path name in the first element of a snapshot If the structure defines an extension then the structure must have context information element.base cannot appear if there is no base on the structure definition A structure must have a base unless abstract = true element.base must appear if there is a base on the structure definition 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 A structure must have either a differential, or a snapshot (or both) Element paths must be unique unless the structure is a constraint In any snapshot or differential, all the elements except the first have to have a path that starts with the path of the first + "." In any snapshot or differential, no label, code or requirements on the an element without a "." in the path (e.g. the first element) If the structure is not abstract, or there's a constrained type, then there SHALL be a base
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-13: element.base must appear if there is a base on the structure definition (xpath: not(f:constrainedType) or not(f:snapshot/f:element[not(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:
Base definition of a data type (example: Quantity - 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"
}
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:
Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.
<!-- from Resource: id, meta, implicitRules, and language --> <!-- from DomainResource: text, contained, extension, and modifierExtension --> <url value="[uri]"/><!-- 1..1 Absolute URL used to reference this StructureDefinition --> <identifier><!-- 0..* Identifier Other identifiers for the StructureDefinition --></identifier> <version value="[string]"/><!-- 0..1 Logical id for this version of the StructureDefinition --> <name value="[string]"/><!-- 1..1 Informal name for this StructureDefinition --> <display value="[string]"/><!-- 0..1 Use this name when displaying the value --> <status value="[code]"/><!-- 1..1 draft | active | retired --> <experimental value="[boolean]"/><!-- 0..1 If for testing purposes, not real usage --> <publisher value="[string]"/><!-- 0..1 Name of the publisher (Organization or individual) --> <contact> <!-- 0..* Contact details of the publisher --> <name value="[string]"/><!-- 0..1 Name of a individual to contact --> <telecom><!-- 0..* ContactPoint Contact details for individual or publisher --></telecom> </contact> <date value="[dateTime]"/><!-- 0..1 Date for this version of the StructureDefinition --> <description value="[string]"/><!-- 0..1 Natural language description of the StructureDefinition --> <useContext><!-- 0..* CodeableConcept Content intends to support these contexts --></useContext> <requirements value="[string]"/><!-- 0..1 Scope and Usage this structure definition is for --> <copyright value="[string]"/><!-- 0..1 Use and/or publishing restrictions --> <code><!-- 0..* Coding Assist with indexing and finding --></code> <fhirVersion value="[id]"/><!-- 0..1 FHIR Version this StructureDefinition targets --> <mapping> <!-- 0..* External specification that the content is mapped to --> <identity value="[id]"/><!-- 1..1 Internal id when this mapping is used --> <uri value="[uri]"/><!--
0..1 Identifies what this mapping refers to --> <name value="[string]"/><!--