[%settitle Element Definition%] [%file newheader%] [%file newnavbar%] <%dtxheader base ElementDefinition%>

Element Definition

Types Framework Cross Reference: Base Types | Datatypes | Resources | Patterns

The definition of an element in a resource or an extension. The definition includes:

• Path (name), cardinality, and datatype
• Definitions, usage notes, and requirements
• Default or fixed values
• Constraints, length limits, and other usage rules
• Terminology Binding
• Mappings to other specifications
• Structural Usage Information such as Slicing

The ElementDefinition type is the core of the FHIR metadata layer, and is closely (conceptually) aligned to ISO 11179. All the data elements defined in this specification are published as a collection of data elements (XML or JSON).

ElementDefinition is used in [%dtusage ElementDefinition%]

Content

[%dt ElementDefinition 1%]

Constraints

[%dt.constraints ElementDefinition%]

Use of ElementDefinition.path

The path element is the most important property of the element definition. It both names the element, and locates the element within a hierarchy defined within a particular context. Within the FHIR specification, there is only one original definition for each path. This is the master definition to which all the other definitions with the same path must conform.

All elements defined within the FHIR specification itself are defined within a StructureDefinition that defines a resource, or a datatype. This defines the identity of the element and provides the context in which the meaning of the element is understood. When Elements are defined, the following rules apply:

• Element names (the parts of a path delineated by the '.' character) SHALL NOT contain whitespace (i.e., Unicode characters marked as whitespace)
• Element names SHALL NOT contain the characters ,:;'"/|?!@#$%^&*()[]{}
• Element names SHOULD not contain non-ASCII characters
• Element names SHALL NOT exceed 64 characters in length
• Element paths cannot imply elements that are not explicitly defined i.e., a.b.c.d cannot be defined unless a.b.c is explicitly defined
• By convention, each path starts with an uppercase letter (type) but all the element names that follow this are lowercase (not type names). All resources and datatypes (except for Primitive datatypes) follow this convention, but logical models are not required to do so

If the element is polymorphic (has more than one datatype), then the end of the path for the element SHALL be "[x]" to designate that the name of the element may vary when serialized. The "[x]" is not considered to be part of the official element name, though it may frequently appear in documentation that way.

Elements may be defined in:

• StructureDefinitions of kind = resource, complex-type or primitive-type, where derivation = specialization. These are either Resources or Datatypes defined in the specification
• StructureDefinitions of kind = logical
• Data Elements

StructureDefinitions with derivation = constraint (i.e., Resource and Datatype profiles) are not allowed to define or include ElementDefinitions with a path not defined within the base type definition from which they derive (e.g., in the FHIR specification).

ElementDefinition.id

In addition to the path, every ElementDefinition SHALL have a populated id, and the id SHALL have a unique value populated by following this algorithm:

• The id will be constructed as a dot separated string, each part corresponding to a token in the path
• For each token in the path, use the syntax pathpart:slicename/reslicename
• For type choice elements, the id reflects the type slice. e.g., For path = Patient.deceased[x], the id of the boolean slice type element is Patient.deceased[x]:deceasedBoolean

Note that in a profile with no slices, this id will match the path exactly and entirely. id values constructed in this fashion are unique, and persistent, and may be used as the target of external references into the definition, where necessary.

Interpretation of ElementDefinition in different contexts

The datatype ElementDefinition is used in StructureDefinition. The way its elements are to be used and interpreted depends on the context:

Notes:♉

• The root element is the element without . separators in the path. It is not always present in differentials
• Expected/Not Expected: this is used in the table to indicate that the element SHOULD or SHOULD NOT be present, but that real world StructureDefinitions may be encountered that differ from this guidance, and that these are not invalid
• Type definition: A StructureDefinition without a baseDefinition element, or where the derivation type is 'specialization'
• Constraint definition: A StructureDefinition with a baseDefinition element and a derivation of 'constraint' - e.g., a definition of a structure that constrains another base structure, referring to the differential portion
• †: The element's presence, and value, must match the definition in the base definition
• ‡: The element content must be consistent with that matching element in the base definition
• ♉︎: In general base definitions should not set mustSupport to true, and no HL7 resources do - mustSupport is usually associated with specific contexts of use
• ∆: Additional constraints and mappings can be defined, but they do not replace the ones in the base definition
• §: The cardinality on a type places constraints on references to that type. i.e., profiles referencing the type must fall within the cardinality bounds of the type itself. This most commonly occurs with Extension profiles, where the profile may prohibit the extension from repeating (max=1), or less commonly, make the extension mandatory (min=1) - i.e., if the extension is referenced in a profile, it must be marked as mandatory.
• For some simple types, rather than pointing to a FHIR datatype, the element will be defined as having a datatype defined by [FHIRPath]. e.g., http://hl7.org/fhirpath/System.String. This occurs when the generic behavior of the FHIR primitive type is not desired (e.g., inheriting extension, id, etc.). Implementations should map these FHIRPath datatypes to the appropriate simple datatype defined in their implementation language. For example, in Java, FHIRPath System.String might best map to the `java.lang.String` class.
• In addition, when an element has a datatype of http://hl7.org/fhirpath/System.String then it will typically also include a structuredefinition-fhir-type extension. This extension might further constrain the allowed value of an element that might be treated as a string. For example, limiting the permitted value regex, length, etc. to the corresponding FHIR-defined datatype (but NOT permitting the additional elements such as id and extension). If the extension is not present, no additional constraints apply.

The use of Path and type depends more deeply on the context where the ElementDefinition is used:

There are additional notes about the use of ElementDefinition when defining Extensions on the Defining Extensions page.

Rules about Slicing

For a description of slicing, see Slicing

• Slicing is only allowed when constraining an existing structure
• slicing can only be used on the first repetition of an element. This first element that declares slicing is considered to be the slicing entry
• All elements following the first repeat that containing a slicing SHALL have a sliceName
• The special slice name @default applies to all entries that are not in any other slice
• The first entry (the one having the slicing information) is understood to be the set of constraints that apply to all slices and entries, whether they have a defined slice or not It's use follows the "normal case", except:
  • slicing must be present
  • min governs the number of total occurrences of the sliced element including the number of occurrences in the open portion of the slice (individual slices may have a different min value).
  • the constraints that apply across all slices and entries of the element are: max, type (code, profile, targetProfile, aggregation and versioning), fixed[x], pattern[x], minValue[x], maxValue[x], maxLength, constraints, required and extensible bindings (including additional bindings), mustHaveValue, valueAlternatives. Obligations apply across all slices unless the obligation specifies an 'applicable-number'
  • mustSupport assertions that do not specify otherwise cannot be assumed to apply to all slices and entries. This is for legacy reasons - the only way to determine the applicability of mustSupport and unspecified obligations is to read the applicable documentation, and in the absence of this, consult the relevant implementation community (see further discussion on the implementation obligations page). Note that a slice labelled as must-support can't be considered to have no need to support just because the slicer element is not labelled as must-support - the documentation (if available) must be consulted.

Constraining elements with a choice of Type

Elements that allow a choice of multiple types can be constrained. In principle, there are two different types of constraints to apply:

• A constraint that applies to the element as a whole - e.g., as restricting the cardinality, or limiting the choice of types
• A constraint that applies to the use of a particular type - e.g., value set binding

When constraining elements with multiple types, the following rules apply:

• Constraints limiting the acceptable list of types must be applied to the original "[x]" element as this is where the list of acceptable types is defined
• The inclusion of a type specific element (such as "Patient.deceased[x]:deceasedBoolean") SHALL NOT be interpreted as constraining allowed types, but instead, it constrains the use of a particular type
• the original element SHALL always be represented in a snapshot; the type specific variants are only represented when needed

Rules about min and max

• If there is no StructureDefinition.baseDefinition: min and max are always required
• Otherwise, in StructureDefinition.differential: min and max are always optional; if they are not present, they default to the min and max from the base definition
• In StructureDefinition.snapshot: min and max are always required
• If min = 0, and there is a fixed or pattern value present, the fixed or pattern value only applies if the element is actually present. If the element is omitted, it is NOT treated as though the fixed value or pattern had been specified

Primitive Values

All primitive data types have a value and also extensions. Even if the element is present, the value might not be present; instead, an extension may be present the either provides information about why the value is not present, or provides an expression that might be used to generate a value in a particular context. Some common extensions that might appear in place of a primitive value:

• data-absent-reason
• nullflavor
• originalText
• expression

In many cases, profiles want to make a primitive element required (min = 1), and also want to say that when a primitive element is present, the value must be present, since the value is what is processed by applications. The flag mustHaveValue can be set to true to indicate that the primitive data type must have value if present (so it has impact whatever the value of min). Note that this flag is a short cut, equivalent to the profile walking into the primitive data type and setting min = 1 for the value. The short cut is preferable because it's simpler and more concise for implementers.

Alternatively, profiles may wish to allow the primitive value to be replaced by some extensions but not others. In this case, the profiles can list the allowable extensions using the valueAlternatives element, which contains a list of the extensions that can appear if the primitive value is not present. Note that this list is a short cut for actually profiling the extensions on the primitive data type and making a co-occurence constraint, but has no effect when the value is present.

For further discussion regarding populating primitive values, see Exchanging Data using FHIR.

Rules about Aggregation

• If an aggregationMode is present in the definition, the 'reference' element SHALL be present and have a value and the target of the reference SHALL be aggregated as defined
• If type.versioning is present in the definition, the 'reference' element SHALL be present and have a value and the reference SHALL be populated as the versioning constraint dictates.

Missing Elements

Most elements have a minimum cardinality of 0, which means that they may be missing from a resource when it is exchanged between systems. Generally, when an element is missing, all that an application processing the resource can say about the element is that the value is unknown - it may have a correct value, but it has not been provided for security or workflow reasons. On the other hand, it might not have a value at all. All the application can say is that the value is unknown.

This also applies when the element is present, but has no value or child elements, and only has extensions instead.

However, for some elements, this specification makes specific rules about what it means if the element is missing. Constraints on other structures cannot change the missing meaning of an element. Here is a list of all elements with a default value or a missing meaning:

<%missing-element-list%>

This specification does not define any default values for resources or datatypes because:

• The value must be known by all implementations
• When an element has a default value, it can never be unknown - e.g., it is implicitly mandatory
• The default value can never be changed
• The presence of a default value interacts with minimum cardinality and the :missing search token in ways that create confusion for implementations

Note that default values can be defined in Logical Models.

Bindings / Additional Bindings

For further information about bindings, see Terminology bindings.

Must-support

The primary focus of the FHIR specification is on correct application behavior around what is exchanged and how: valid APIs and resource instances. However many FHIR implementation guides are interested in specifying additional obligations about how the applications involved handle the data that is being exchanged.

Element Definitions use the property mustSupport to indicate that there are rules that apply to how the data is handled. In addition, the <%extension http://hl7.org/fhir/StructureDefinition/obligation%> extension can be used to make more detailed statements about application behavior. See Implementation Obligations for the proper use of these features.

[%file newfooter%] try { var currentTabIndex = sessionStorage.getItem('fhir-resource-tab-index'); } catch (exception) {} if (!currentTabIndex) currentTabIndex = '0'; $('#tabs-ElementDefinition').tabs({ active: currentTabIndex, activate: function(event, ui) { store(ui.newTab.index()); } }); function store(currentTab) { document.activeElement.blur(); try { sessionStorage.setItem('fhir-resource-tab-index', currentTab); } catch (exception) {} $('#tabs-ElementDefinition').tabs('option', 'active', currentTab); }