STU 3 Candidate

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

6.18 Resource StructureDefinition - Content

FHIR Infrastructure Work GroupMaturity Level: 2Compartments: 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.18.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.

Note that as part of the specification itself, a full set of structure definitions for all resources and data types is published.

6.18.2 Boundaries and Relationships

  • 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.18.3 Background and Context

Implementers should be familiar with the background and concepts described in Profiling FHIR before working with this resource.

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

urlThe 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
identifierOther 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

nameA free text natural language name identifying the structure
publisherDetails of the individual or organization who accepts responsibility for publishing the structure. This helps establish the "authority/credibility" of the structure.
telecomContact details to assist a user in finding and communicating with the publisher
descriptionA free text natural language description of the structure and its use
requirementsThe Scope and Usage that this structure was created to meet
codeA set of terms from external terminologies that may be used to assist with indexing and searching of profiles
statusThe status of the structure allows filtering of profiles that are appropriate for use vs. not. See the Status Codes
experimentalThis structure was authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usage
dateThe date this version of the structure was published
fhirVersionThe 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.
typetodo
contextTypetodo
contexttodo

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

This resource is referenced by ConceptMap, Conformance, ImplementationGuide, ModuleDefinition and OperationDefinition

6.18.4 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. StructureDefinition IDomainResourceStructural 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
If the structure is not abstract, or there's a constrained type, then there SHALL be a base
baseType implies derivation
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)
... url Σ1..1uriAbsolute URL used to reference this StructureDefinition
... identifier Σ0..*IdentifierOther identifiers for the StructureDefinition
... version Σ0..1stringLogical id for this version of the StructureDefinition
... name Σ1..1stringInformal name for this StructureDefinition
... display Σ0..1stringUse this name when displaying the value
... status ?! Σ1..1codedraft | active | retired
ConformanceResourceStatus (Required)
... experimental Σ0..1booleanIf for testing purposes, not real usage
... publisher Σ0..1stringName of the publisher (Organization or individual)
... contact Σ0..*BackboneElementContact details of the publisher
.... name Σ0..1stringName of an individual to contact
.... telecom Σ0..*ContactPointContact details for individual or publisher
... date Σ0..1dateTimeDate for this version of the StructureDefinition
... description Σ0..1stringNatural language description of the StructureDefinition
... useContext Σ0..*CodeableConceptContent intends to support these contexts
Context of Use ValueSet (Extensible)
... requirements 0..1stringScope and Usage this structure definition is for
... copyright 0..1stringUse and/or publishing restrictions
... code Σ0..*CodingAssist with indexing and finding
Structure Definition Codes (Example)
... fhirVersion Σ0..1idFHIR Version this StructureDefinition targets
... mapping I0..*BackboneElementExternal specification that the content is mapped to
Must have at a name or a uri (or both)
.... identity 1..1idInternal id when this mapping is used
.... uri I0..1uriIdentifies what this mapping refers to
.... name I0..1stringNames what this mapping refers to
.... comments 0..1stringVersions, Issues, Scope limitations etc.
... kind Σ1..1codedatatype | resource | logical
StructureDefinitionKind (Required)
... abstract Σ1..1booleanWhether the structure is abstract
... contextType Σ I0..1coderesource | datatype | extension
ExtensionContext (Required)
... context Σ I0..*stringWhere the extension can be used in instances
... baseType Σ I0..1codeAny datatype or resource, including abstract ones
FHIRDefinedType (Required)
... baseDefinition Σ I0..1uriDefinition that this type is constrained/specialized from
... derivation Σ I0..1codespecialization | constraint - How relates to base definition
TypeDerivationRule (Required)
... snapshot I0..1BackboneElementSnapshot view of the structure
Each element definition in a snapshot must have a formal definition and cardinalities
.... element I1..*ElementDefinitionDefinition of elements in the resource (if no StructureDefinition)
... differential I0..1BackboneElementDifferential view of the structure
.... element 1..*ElementDefinitionDefinition of elements in the resource (if no StructureDefinition)

doco Documentation for this format

UML Diagram

StructureDefinition (DomainResource)An absolute URL that is used to identify this structure definition when it is referenced in a specification, model, design or an instance. This SHALL be a URL, SHOULD be globally unique, and SHOULD be an address at which this structure definition is (or will be) publishedurl : uri [1..1]Formal identifier that is used to identify this StructureDefinition when it is represented in other formats, or referenced in a specification, model, design or an instance (should be globally unique OID, UUID, or URI), (if it's not possible to use the literal URI)identifier : Identifier [0..*]The identifier that is used to identify this version of the StructureDefinition when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the StructureDefinition author manuallyversion : string [0..1]A free text natural language name identifying the StructureDefinitionname : string [1..1]Defined so that applications can use this name when displaying the value of the extension to the userdisplay : string [0..1]The status of the StructureDefinition (this element modifies the meaning of other elements)status : code [1..1] « The lifecycle status of a Value Set or Concept Map. (Strength=Required)ConformanceResourceStatus! »This StructureDefinition was authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usageexperimental : boolean [0..1]The name of the individual or organization that published the structure definitionpublisher : string [0..1]The date this version of the structure definition was published. The date must change when the business version changes, if it does, and it must change if the status code changes. In addition, it should change when the substantive content of the structure definition changesdate : dateTime [0..1]A free text natural language description of the StructureDefinition and its usedescription : string [0..1]The content was developed with a focus and intent of supporting the contexts that are listed. These terms may be used to assist with indexing and searching of structure definitionsuseContext : CodeableConcept [0..*] « Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use. (Strength=Extensible)Context of Use ValueSet+ »Explains why this structure definition is needed and why it's been constrained as it hasrequirements : string [0..1]A copyright statement relating to the structure definition and/or its contents. Copyright statements are generally legal restrictions on the use and publishing of the details of the constraints and mappingscopyright : string [0..1]A set of terms from external terminologies that may be used to assist with indexing and searching of templatescode : Coding [0..*] « Codes for the meaning of the defined structure (SNOMED CT and LOINC codes, as an example). (Strength=Example)Structure Definition ?? »The version of the FHIR specification on which this StructureDefinition is based - this is the formal version of the specification, without the revision number, e.g. [publication].[major].[minor], which is 1.4.0 for this versionfhirVersion : id [0..1]Defines the kind of structure that this definition is describingkind : code [1..1] « Defines the type of structure that a definition is describing. (Strength=Required)StructureDefinitionKind! »Whether structure this definition describes is abstract or not - that is, whether an actual exchanged item can ever be of this typeabstract : boolean [1..1]If this is an extension, Identifies the context within FHIR resources where the extension can be usedcontextType : code [0..1] « How an extension context is interpreted. (Strength=Required)ExtensionContext! »Identifies the types of resource or data type elements to which the extension can be appliedcontext : string [0..*]The type of type that this structure is derived from - a data type, an extension, a resource, including abstract ones. If this field is present, it indicates that the structure definition is deriving from this type. If it is not present, then the structure definition is the definition of a base abstract structurebaseType : code [0..1] « Either a resource or a data type. (Strength=Required)FHIRDefinedType! »An absolute URI that is the base structure from which this type is derived, either by specialization or constraintbaseDefinition : uri [0..1]How the type relates to the baseDefinitionderivation : code [0..1] « How a type relates to it's baseDefinition. (Strength=Required)TypeDerivationRule! »ContactThe name of an individual to contact regarding the structure definitionname : string [0..1]Contact details for individual (if a name was provided) or the publishertelecom : ContactPoint [0..*]MappingAn Internal id that is used to identify this mapping set when specific mappings are madeidentity : id [1..1]An absolute URI that identifies the specification that this mapping is expressed touri : uri [0..1]A name for the specification that is being mapped toname : string [0..1]Comments about this mapping, including version notes, issues, scope limitations, and other important notes for usagecomments : string [0..1]SnapshotCaptures constraints on each element within the resourceelement : ElementDefinition [1..*]DifferentialCaptures constraints on each element within the resourceelement : ElementDefinition [1..*]Contacts to assist a user in finding and communicating with the publishercontact[0..*]An external specification that the content is mapped tomapping[0..*]A snapshot view is expressed in a stand alone form that can be used and interpreted without considering the base StructureDefinitionsnapshot[0..1]A differential view is expressed relative to the base StructureDefinition - a statement of differences that it appliesdifferential[0..1]

XML Template

<StructureDefinition xmlns="http://hl7.org/fhir"> doco
 <!-- 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 an 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]"/><!-- ?? 0..1 Names what this mapping refers to -->
  <comments value="[string]"/><!-- 0..1 Versions, Issues, Scope limitations etc. -->
 </mapping>
 <kind value="[code]"/><!-- 1..1 datatype | resource | logical -->
 <abstract value="[boolean]"/><!-- 1..1 Whether the structure is abstract -->
 <contextType value="[code]"/><!-- ?? 0..1 resource | datatype | extension -->
 <context value="[string]"/><!-- ?? 0..* Where the extension can be used in instances -->
 <baseType value="[code]"/><!-- ?? 0..1 Any datatype or resource, including abstract ones -->
 <baseDefinition value="[uri]"/><!-- ?? 0..1 Definition that this type is constrained/specialized from -->
 <derivation value="[code]"/><!-- ?? 0..1 specialization | constraint - How relates to base definition -->
 <snapshot>  <!-- ?? 0..1 Snapshot view of the structure -->
  <element><!-- ?? 1..* ElementDefinition Definition of elements in the resource (if no StructureDefinition) --></element>
 </snapshot>
 <differential>  <!-- ?? 0..1 Differential view of the structure -->
  <element><!-- 1..* ElementDefinition Definition of elements in the resource (if no StructureDefinition) --></element>
 </differential>
</StructureDefinition>

JSON Template

{doco
  "resourceType" : "StructureDefinition",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "url" : "<uri>", // R!  Absolute URL used to reference this StructureDefinition
  "identifier" : [{ Identifier }], // Other identifiers for the StructureDefinition
  "version" : "<string>", // Logical id for this version of the StructureDefinition
  "name" : "<string>", // R!  Informal name for this StructureDefinition
  "display" : "<string>", // Use this name when displaying the value
  "status" : "<code>", // R!  draft | active | retired
  "experimental" : <boolean>, // If for testing purposes, not real usage
  "publisher" : "<string>", // Name of the publisher (Organization or individual)
  "contact" : [{ // Contact details of the publisher
    "name" : "<string>", // Name of an individual to contact
    "telecom" : [{ ContactPoint }] // Contact details for individual or publisher
  }],
  "date" : "<dateTime>", // Date for this version of the StructureDefinition
  "description" : "<string>", // Natural language description of the StructureDefinition
  "useContext" : [{ CodeableConcept }], // Content intends to support these contexts
  "requirements" : "<string>", // Scope and Usage this structure definition is for
  "copyright" : "<string>", // Use and/or publishing restrictions
  "code" : [{ Coding }], // Assist with indexing and finding
  "fhirVersion" : "<id>", // FHIR Version this StructureDefinition targets
  "mapping" : [{ // External specification that the content is mapped to
    "identity" : "<id>", // R!  Internal id when this mapping is used
    "uri" : "<uri>", // C? Identifies what this mapping refers to
    "name" : "<string>", // C? Names what this mapping refers to
    "comments" : "<string>" // Versions, Issues, Scope limitations etc.
  }],
  "kind" : "<code>", // R!  datatype | resource | logical
  "abstract" : <boolean>, // R!  Whether the structure is abstract
  "contextType" : "<code>", // C? resource | datatype | extension
  "context" : ["<string>"], // C? Where the extension can be used in instances
  "baseType" : "<code>", // C? Any datatype or resource, including abstract ones
  "baseDefinition" : "<uri>", // C? Definition that this type is constrained/specialized from
  "derivation" : "<code>", // C? specialization | constraint - How relates to base definition
  "snapshot" : { // C? Snapshot view of the structure
    "element" : [{ ElementDefinition }] // C? R!  Definition of elements in the resource (if no StructureDefinition)
  },
  "differential" : { // C? Differential view of the structure
    "element" : [{ ElementDefinition }] // R!  Definition of elements in the resource (if no StructureDefinition)
  }
}

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. StructureDefinition IDomainResourceStructural 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
If the structure is not abstract, or there's a constrained type, then there SHALL be a base
baseType implies derivation
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)
... url Σ1..1uriAbsolute URL used to reference this StructureDefinition
... identifier Σ0..*IdentifierOther identifiers for the StructureDefinition
... version Σ0..1stringLogical id for this version of the StructureDefinition
... name Σ1..1stringInformal name for this StructureDefinition
... display Σ0..1stringUse this name when displaying the value
... status ?! Σ1..1codedraft | active | retired
ConformanceResourceStatus (Required)
... experimental Σ0..1booleanIf for testing purposes, not real usage
... publisher Σ0..1stringName of the publisher (Organization or individual)
... contact Σ0..*BackboneElementContact details of the publisher
.... name Σ0..1stringName of an individual to contact
.... telecom Σ0..*ContactPointContact details for individual or publisher
... date Σ0..1dateTimeDate for this version of the StructureDefinition
... description Σ0..1stringNatural language description of the StructureDefinition
... useContext Σ0..*CodeableConceptContent intends to support these contexts
Context of Use ValueSet (Extensible)
... requirements 0..1stringScope and Usage this structure definition is for
... copyright 0..1stringUse and/or publishing restrictions
... code Σ0..*CodingAssist with indexing and finding
Structure Definition Codes (Example)
... fhirVersion Σ0..1idFHIR Version this StructureDefinition targets
... mapping I0..*BackboneElementExternal specification that the content is mapped to
Must have at a name or a uri (or both)
.... identity 1..1idInternal id when this mapping is used
.... uri I0..1uriIdentifies what this mapping refers to
.... name I0..1stringNames what this mapping refers to
.... comments 0..1stringVersions, Issues, Scope limitations etc.
... kind Σ1..1codedatatype | resource | logical
StructureDefinitionKind (Required)
... abstract Σ1..1booleanWhether the structure is abstract
... contextType Σ I0..1coderesource | datatype | extension
ExtensionContext (Required)
... context Σ I0..*stringWhere the extension can be used in instances
... baseType Σ I0..1codeAny datatype or resource, including abstract ones
FHIRDefinedType (Required)
... baseDefinition Σ I0..1uriDefinition that this type is constrained/specialized from
... derivation Σ I0..1codespecialization | constraint - How relates to base definition
TypeDerivationRule (Required)
... snapshot I0..1BackboneElementSnapshot view of the structure
Each element definition in a snapshot must have a formal definition and cardinalities
.... element I1..*ElementDefinitionDefinition of elements in the resource (if no StructureDefinition)
... differential I0..1BackboneElementDifferential view of the structure
.... element 1..*ElementDefinitionDefinition of elements in the resource (if no StructureDefinition)

doco Documentation for this format

UML Diagram

StructureDefinition (DomainResource)An absolute URL that is used to identify this structure definition when it is referenced in a specification, model, design or an instance. This SHALL be a URL, SHOULD be globally unique, and SHOULD be an address at which this structure definition is (or will be) publishedurl : uri [1..1]Formal identifier that is used to identify this StructureDefinition when it is represented in other formats, or referenced in a specification, model, design or an instance (should be globally unique OID, UUID, or URI), (if it's not possible to use the literal URI)identifier : Identifier [0..*]The identifier that is used to identify this version of the StructureDefinition when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the StructureDefinition author manuallyversion : string [0..1]A free text natural language name identifying the StructureDefinitionname : string [1..1]Defined so that applications can use this name when displaying the value of the extension to the userdisplay : string [0..1]The status of the StructureDefinition (this element modifies the meaning of other elements)status : code [1..1] « The lifecycle status of a Value Set or Concept Map. (Strength=Required)ConformanceResourceStatus! »This StructureDefinition was authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usageexperimental : boolean [0..1]The name of the individual or organization that published the structure definitionpublisher : string [0..1]The date this version of the structure definition was published. The date must change when the business version changes, if it does, and it must change if the status code changes. In addition, it should change when the substantive content of the structure definition changesdate : dateTime [0..1]A free text natural language description of the StructureDefinition and its usedescription : string [0..1]The content was developed with a focus and intent of supporting the contexts that are listed. These terms may be used to assist with indexing and searching of structure definitionsuseContext : CodeableConcept [0..*] « Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use. (Strength=Extensible)Context of Use ValueSet+ »Explains why this structure definition is needed and why it's been constrained as it hasrequirements : string [0..1]A copyright statement relating to the structure definition and/or its contents. Copyright statements are generally legal restrictions on the use and publishing of the details of the constraints and mappingscopyright : string [0..1]A set of terms from external terminologies that may be used to assist with indexing and searching of templatescode : Coding [0..*] « Codes for the meaning of the defined structure (SNOMED CT and LOINC codes, as an example). (Strength=Example)Structure Definition ?? »The version of the FHIR specification on which this StructureDefinition is based - this is the formal version of the specification, without the revision number, e.g. [publication].[major].[minor], which is 1.4.0 for this versionfhirVersion : id [0..1]Defines the kind of structure that this definition is describingkind : code [1..1] « Defines the type of structure that a definition is describing. (Strength=Required)StructureDefinitionKind! »Whether structure this definition describes is abstract or not - that is, whether an actual exchanged item can ever be of this typeabstract : boolean [1..1]If this is an extension, Identifies the context within FHIR resources where the extension can be usedcontextType : code [0..1] « How an extension context is interpreted. (Strength=Required)ExtensionContext! »Identifies the types of resource or data type elements to which the extension can be appliedcontext : string [0..*]The type of type that this structure is derived from - a data type, an extension, a resource, including abstract ones. If this field is present, it indicates that the structure definition is deriving from this type. If it is not present, then the structure definition is the definition of a base abstract structurebaseType : code [0..1] « Either a resource or a data type. (Strength=Required)FHIRDefinedType! »An absolute URI that is the base structure from which this type is derived, either by specialization or constraintbaseDefinition : uri [0..1]How the type relates to the baseDefinitionderivation : code [0..1] « How a type relates to it's baseDefinition. (Strength=Required)TypeDerivationRule! »ContactThe name of an individual to contact regarding the structure definitionname : string [0..1]Contact details for individual (if a name was provided) or the publishertelecom : ContactPoint [0..*]MappingAn Internal id that is used to identify this mapping set when specific mappings are madeidentity : id [1..1]An absolute URI that identifies the specification that this mapping is expressed touri : uri [0..1]A name for the specification that is being mapped toname : string [0..1]Comments about this mapping, including version notes, issues, scope limitations, and other important notes for usagecomments : string [0..1]SnapshotCaptures constraints on each element within the resourceelement : ElementDefinition [1..*]DifferentialCaptures constraints on each element within the resourceelement : ElementDefinition [1..*]Contacts to assist a user in finding and communicating with the publishercontact[0..*]An external specification that the content is mapped tomapping[0..*]A snapshot view is expressed in a stand alone form that can be used and interpreted without considering the base StructureDefinitionsnapshot[0..1]A differential view is expressed relative to the base StructureDefinition - a statement of differences that it appliesdifferential[0..1]

XML Template

<StructureDefinition xmlns="http://hl7.org/fhir"> doco
 <!-- 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 an 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]"/><!-- ?? 0..1 Names what this mapping refers to -->
  <comments value="[string]"/><!-- 0..1 Versions, Issues, Scope limitations etc. -->
 </mapping>
 <kind value="[code]"/><!-- 1..1 datatype | resource | logical -->
 <abstract value="[boolean]"/><!-- 1..1 Whether the structure is abstract -->
 <contextType value="[code]"/><!-- ?? 0..1 resource | datatype | extension -->
 <context value="[string]"/><!-- ?? 0..* Where the extension can be used in instances -->
 <baseType value="[code]"/><!-- ?? 0..1 Any datatype or resource, including abstract ones -->
 <baseDefinition value="[uri]"/><!-- ?? 0..1 Definition that this type is constrained/specialized from -->
 <derivation value="[code]"/><!-- ?? 0..1 specialization | constraint - How relates to base definition -->
 <snapshot>  <!-- ?? 0..1 Snapshot view of the structure -->
  <element><!-- ?? 1..* ElementDefinition Definition of elements in the resource (if no StructureDefinition) --></element>
 </snapshot>
 <differential>  <!-- ?? 0..1 Differential view of the structure -->
  <element><!-- 1..* ElementDefinition Definition of elements in the resource (if no StructureDefinition) --></element>
 </differential>
</StructureDefinition>

JSON Template

{doco
  "resourceType" : "StructureDefinition",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "url" : "<uri>", // R!  Absolute URL used to reference this StructureDefinition
  "identifier" : [{ Identifier }], // Other identifiers for the StructureDefinition
  "version" : "<string>", // Logical id for this version of the StructureDefinition
  "name" : "<string>", // R!  Informal name for this StructureDefinition
  "display" : "<string>", // Use this name when displaying the value
  "status" : "<code>", // R!  draft | active | retired
  "experimental" : <boolean>, // If for testing purposes, not real usage
  "publisher" : "<string>", // Name of the publisher (Organization or individual)
  "contact" : [{ // Contact details of the publisher
    "name" : "<string>", // Name of an individual to contact
    "telecom" : [{ ContactPoint }] // Contact details for individual or publisher
  }],
  "date" : "<dateTime>", // Date for this version of the StructureDefinition
  "description" : "<string>", // Natural language description of the StructureDefinition
  "useContext" : [{ CodeableConcept }], // Content intends to support these contexts
  "requirements" : "<string>", // Scope and Usage this structure definition is for
  "copyright" : "<string>", // Use and/or publishing restrictions
  "code" : [{ Coding }], // Assist with indexing and finding
  "fhirVersion" : "<id>", // FHIR Version this StructureDefinition targets
  "mapping" : [{ // External specification that the content is mapped to
    "identity" : "<id>", // R!  Internal id when this mapping is used
    "uri" : "<uri>", // C? Identifies what this mapping refers to
    "name" : "<string>", // C? Names what this mapping refers to
    "comments" : "<string>" // Versions, Issues, Scope limitations etc.
  }],
  "kind" : "<code>", // R!  datatype | resource | logical
  "abstract" : <boolean>, // R!  Whether the structure is abstract
  "contextType" : "<code>", // C? resource | datatype | extension
  "context" : ["<string>"], // C? Where the extension can be used in instances
  "baseType" : "<code>", // C? Any datatype or resource, including abstract ones
  "baseDefinition" : "<uri>", // C? Definition that this type is constrained/specialized from
  "derivation" : "<code>", // C? specialization | constraint - How relates to base definition
  "snapshot" : { // C? Snapshot view of the structure
    "element" : [{ ElementDefinition }] // C? R!  Definition of elements in the resource (if no StructureDefinition)
  },
  "differential" : { // C? Differential view of the structure
    "element" : [{ ElementDefinition }] // R!  Definition of elements in the resource (if no StructureDefinition)
  }
}

 

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

6.18.4.1 Terminology Bindings

PathDefinitionTypeReference
StructureDefinition.status The lifecycle status of a Value Set or Concept Map.RequiredConformanceResourceStatus
StructureDefinition.useContext Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use.ExtensibleContext of Use ValueSet
StructureDefinition.code Codes for the meaning of the defined structure (SNOMED CT and LOINC codes, as an example).ExampleStructure Definition Codes
StructureDefinition.kind Defines the type of structure that a definition is describing.RequiredStructureDefinitionKind
StructureDefinition.contextType How an extension context is interpreted.RequiredExtensionContext
StructureDefinition.baseType Either a resource or a data type.Requiredhttp://hl7.org/fhir/valueset/defined-typesFHIRDefinedType
StructureDefinition.derivation How a type relates to it's baseDefinition.RequiredTypeDerivationRule

6.18.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 constrained type, its content must match the path name in the first element of a snapshot (expression: derivation = 'constraint' implies baseType and (snapshot.empty() or snapshot.element.first().path = baseType))
  • sdf-12: element.base cannot appear if there is no base on the structure definition (expression: snapshot.element.base implies baseType)
  • sdf-13: baseType implies derivation (expression: baseType implies derivation)
  • sdf-2: On StructureDefinition.mapping: Must have at a name or a uri (or both) (expression on StructureDefinition.mapping: name or uri)
  • 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, or there's a constrained type, then there SHALL be a base (expression: abstract = true or (baseType and baseDefinition))
  • sdf-5: If the structure defines an extension then the structure must have context information (expression: baseType != 'Extension' or (context and contextType))
  • sdf-6: A structure must have either a differential, or a snapshot (or both) (expression: snapshot or 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 (expression: (derivation = 'constraint') or (url = 'http://hl7.org/fhir/StructureDefinition/'+id))
  • 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 + "." (expression: snapshot.element.tail().all(path.startsWith($context.snapshot.element.first().path+'.')) and differential.element.tail().all(path.startsWith($context.differential.element.first().path+'.')))
  • 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())

6.18.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.18.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.18.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.18.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.orgLOINC code for the element
http://snomed.infoSNOMED CT code for the element
http://hl7.org/v3RIM mapping
http://hl7.org/v2HL7 v2 mapping
http://nema.org/dicomDICOM tag mapping
http://w3.org/vcardvCard equivalent field
http://ihe.net/xdsXDS metadata equivalent

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

NameTypeDescriptionPaths
abstracttokenWhether the structure is abstractStructureDefinition.abstract
baseuriDefinition that this type is constrained/specialized fromStructureDefinition.baseDefinition
base-pathtokenPath that identifies the base elementStructureDefinition.snapshot.element.base.path, StructureDefinition.differential.element.base.path
codetokenA code for the profileStructureDefinition.code
contexttokenA use context assigned to the structureStructureDefinition.useContext
context-typetokenresource | datatype | extensionStructureDefinition.contextType
datedateThe profile publication dateStructureDefinition.date
derivationtokenspecialization | constraint - How relates to base definitionStructureDefinition.derivation
descriptionstringText search in the description of the profileStructureDefinition.description
displaystringUse this name when displaying the valueStructureDefinition.display
experimentaltokenIf for testing purposes, not real usageStructureDefinition.experimental
ext-contextstringWhere the extension can be used in instancesStructureDefinition.context
identifiertokenThe identifier of the profileStructureDefinition.identifier
kindtokendatatype | resource | logicalStructureDefinition.kind
namestringName of the profileStructureDefinition.name
pathtokenA path that is constrained in the profileStructureDefinition.snapshot.element.path, StructureDefinition.differential.element.path
publisherstringName of the publisher of the profileStructureDefinition.publisher
statustokenThe current status of the profileStructureDefinition.status
typetokenAny datatype or resource, including abstract onesStructureDefinition.baseType
urluriAbsolute URL used to reference this StructureDefinitionStructureDefinition.url
valuesetreferenceA vocabulary binding referenceStructureDefinition.snapshot.element.binding.valueSet[x]
(ValueSet)
versiontokenThe version identifier of the profileStructureDefinition.version