. Page versions: R5 R4B R4 R3 R2This page is part of the FHIR Specification (v0.11: DSTU 1 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
The FHIR specification defines a set of types that are used for the resource elements. There are two categories of data type: simple / primitive types, imported from XML schema, and complex types, which are re-usable clusters of elements. This page describes the data types. See also the Examples, Formal Definitions and Mappings.
The data types are available as a W3C Schema.
The following table summarizes the primitive types and their simple restrictions that are used in throughout this specification. These types all have extensions, and a value attribute which has the same value domain as defined in the W3C Schema (1.0) specification part 2, with additional constraints marked in bold.
| Primitive Types | ||
| FHIR Name | Schema type | Description |
|---|---|---|
| boolean | xs:boolean | Values can be either true or false (0 and 1 are not valid values) |
| integer | xs:int | A signed 32-bit integer (for larger values, use decimal) |
| decimal | xs:decimal | A rational number. Note: for implementations, do not use a IEEE type floating point type, instead use something that works like a true decimal, with inbuilt precision (e.g. Java BigDecimal). Decimals may not use exponents. |
| base64Binary | xs:base64Binary | A stream of bytes, base64 encoded (RFC 4648) |
| instant | xs:dateTime | An instant in time - known at least to the second and always includes a timezone. Note: This type is for system times, not human times (see date and dateTime below). |
| string | xs:string | A sequence of Unicode characters. Note that strings SHALL not exceed 1MB in size |
| uri | xs:anyURI | A Uniform Resource Identifier Reference. It can be absolute or relative, and may have an optional fragment identifier (RFC 3986) |
| date | union of xs:date, xs:gYearMonth, xs:gYear | A date, or partial date (e.g. just year or year + month) as used in human communication. There is no time zone. Dates must be valid dates. date is a union of the w3c schema types date, gYearMonth, and gYear regex: -?([1-9][0-9]{3,}|0[0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])(Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))? |
| dateTime | union of xs:dateTime, xs:date, xs:gYearMonth, xs:gYear | A date, date-time or partial date (e.g. just year or year + month) as used in human communication. If hours and minutes are specified, a time zone must be populated. Seconds may be provided but may also be ignored. Dates must be valid dates. date is a union of the w3c schema types dateTime, date, gYearMonth, gYear regex:-?([1-9][0-9]{3,}|0[0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T(([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\.[0-9]+)?|(24:00:00(\.0+)?))(Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))? |
| Simple Restrictions | ||
| FHIR Name | Base FHIR Type | Description |
| oid | uri | An OID represented as a URI (RFC 3001): urn:oid:1.2.3.4.5 |
| uuid | uri | A UUID, represented as a URI (RFC 4122): urn:uuid:a5afddf4-e880-459b-876e-e4591b0acc11 |
| code | string | A string which has at least one character and no leading or trailing whitespace, and where there is no whitespace other than single spaces in the contents regex: [^\s]+([\s]+[^\s]+)* |
| id | string | A whole number in the range 0 to 2^64-1 (optionally represented in hex), a uuid, an oid, or any other combination of lowercase letters, numerals, "-" and ".", with a length limit of 36 characters regex: [a-z0-9\-\.]{1,36} |
These types are represented as XML Elements with the value of the type in the value attribute. The name of the element is defined where the type is used. The XML elements may have an id attribute. According to XML schema, leading and trailing whitespace in the value attribute is ignored for the types boolean, integer, decimal, base64Binary, instant, uri, date, dateTime, oid, and uri. Note that this means that the schema aware XML libraries give different attribute values to non schema aware libraries when reading the XML instances. For this reason, the value attribute for these types SHOULD not have leading and trailing spaces. String values should only have leading and trailing spaces if they are part of the content of the value.
The primitive data types can have extensions like any other element in a resource.
These types are represented as XML Elements with child elements with the name of the defined elements of the type. The name of the element is defined where the type is used. Any of the XML elements may have an id attribute. In JSON, the data type is represented by an object with properties named the same as the XML elements. The JSON representation is almost exactly the same, so only the first example has an additional JSON representation.
Complex data types may be "profiled". A profile makes a set of rules about which elements must have values, and what the possible values are.
This type is for containing or referencing attachments - additional data content defined in other formats. The most common use of this type is to include images or reports in some report format such as PDF. However it can be used for any data that has a mime type.
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <contentType value="[code]"/><!-- 1..1 Mime type of the content, with charset etc. --> <language value="[code]"/><!-- 0..1 Human language of the content (BCP-47) --> <data value="[base64Binary]"/><!-- 0..1 Data inline, base64ed --> <url value="[uri]"/><!-- 0..1 Uri where the data can be found --> <size value="[integer]"/><!-- 0..1 Number of bytes of content (if url provided) --> <hash value="[base64Binary]"/><!-- 0..1 Hash of the data (sha-1, base64ed ) --> <title value="[string]"/><!-- 0..1 Label to display in place of the data --> </[name]>
| Path | Definition | Type | Reference |
|---|---|---|---|
| Attachment.contentType | The mime type of an attachment | Incomplete | BCP 13 (RFCs 2045, 2046, 2047, 4288, 4289 and 2049) |
| Attachment.language | A human language | Incomplete | IETF language tag |
The contentType element must always be populated. It can include charset information and other mime type extensions as appropriate. If there is no character set in the contentType then the correct course of action is undefined, though some media types may define a default character set and/or the correct character set may be able to be determined by inspection of the content.
The actual content of the Attachment can be conveyed directly using the data element or a url reference can be provided. If both are provided, the reference must point to the same content as found in the data. The reference can never be reused to point to some different data (i.e. the reference is version specific). The url reference must point to a location that resolves to actual data; some URIs such as cid: meet this requirement.
The hash is included so that applications can verify that the content returned by the url has not changed.
In many cases where Attachment is used, the cardinality is >1;. A valid use of repeats is to convey the same content in different mime types and languages. Guidance on the meaning of repeating elements MUST be provided in the definition of the repeating resource element or extension that references this type. The language element describes the language of the attachment using the codes defined in BCP 47.
Constraints
If neither data nor a url is provided, the value should be understood as an assertion that no content for the specified mimeType and/or xml:lang is available for the reason stated.
The context of use may frequently make rules about the kind of attachment (and therefore, the kind of mime types) that can be used.
A "coding" is a representation of a defined concept using a symbol from a defined "code system" - which may be an enumeration, a list of codes, a full terminology such as SNOMED-CT or LOINC or a formal ontology.
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <system value="[uri]"/><!-- 0..1 Identity of the terminology system --> <code value="[code]"/><!-- 0..1 Symbol in syntax defined by the system --> <display value="[string]"/><!-- 0..1 Representation defined by the system --> </[name]>
The system is a URI that references the enumeration, terminology or ontology that defines the code. The URI may be an OID (urn:oid:) or a UUID (urn:uuid:), a specially defined URI from the named systems list, a url that references a definition of the system or any other URI that uniquely identifies the definitions. This could include a reference to a ValueSet stored in a FHIR server that defines the code system. OIDs and UUIDs may be registered in the HL7 OID registry and should be if the content is shared or exchanged across institutional boundaries.
If present, the code must be a syntactically correct symbol as defined by the system. In some code systems such as SNOMED-CT, the code may be an expression composed of other codes. Note that codes are case sensitive unless specified otherwise by the code system. The display is a text representation of the code defined by the system and can be used to display the meaning of the code by an application that is not aware of the system.
In some cases, the system may not be known - only the code is known. In this case, no useful processing of the code may be performed unless the system can be safely inferred by the context. This practice should be avoided where possible, as information sharing in a wider context is very likely to arise eventually, and codes cannot be used in the absence of a known system.
If the system is present, and there is no code, then this is understood to mean that there is no suitable code in the system in which to represent the code.
If two codings have the same system and code then they have the same meaning. Note that if a code system redefines the meaning of codes across different releases, then the different releases must have different values for system. If either the system or the code differs, then how they are related can only be determined by consulting the definitions of the system(s) and any mappings available.
The correct value to use in the system for a given code-system can be determined by:
Constraints
The context of use (as defined in the resource or applicable profile) usually makes rules about what codes and systems are allowed or required in a particular context by binding the element to a value set.
A Coding is a simple direct reference to a code in a code system. In practice, such a simple reference is very difficult to use - if a system is using text when the correct codes can't be found, or if two different systems are using different terminologies or a different mix of codes and text, the Coding type doesn't provide enough information to make this work. Since such situations are quite a common case, the type CodeableConcept is defined, which allows for multiple Coding elements and/or a text representation. The CodeableConcept is used in resources in preference to the simpler Coding except for a few special cases. Coding is defined separately mainly for use in profiles, where the context of an explicit use case means that the profile can define a better structure than the general case CodeableConcept.
A CodeableConcept represents a field that is usually defined by formal reference to one or more terminologies or ontologies, but may also be defined by the provision of text. This is a common pattern in healthcare data.
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <coding><!-- 0..* Coding Code defined by a terminology system --></coding> <text value="[string]"/><!-- 0..1 Plain text representation of the concept --> <primary value="[idref]"/><!-- 0..1 Which code was chosen directly by the user --> </[name]>
Each "coding" is a representation of the concept using a symbol from a defined "code system" - which may be an enumeration, a list of codes, a full terminology such as SNOMED-CT or LOINC, or a formal ontology. The concept may be coded multiple times in different code systems (or even multiple times in the same code systems, where multiple forms are possible, such as with SNOMED-CT). The different codings may have slightly different granularity due to the differences in the definitions of the underlying codes. The ordering of Codings within a CodeableConcept is undefined.
Whether or not coding elements are present, the text representation of the concept as entered or chosen by the user which most closely represents the intended meaning of the user or concept. Very often the text is the same as a display of one of the codings. One of the codings may be flagged as the primary - the code that the user actually chose directly. If present, the value of the primary element is an xml:id that must match an id attribute on one of the codings.
Constraints
The context of use usually makes rules about what codes and systems are allowed or required in a particular context by binding the element to a value set.
A code taken from a short list of codes that are not defined in a formal code system. Choice is generally used for things like pain scales, questionnaires or formally defined assessment indexes. The possible codes may be ordered with some arbitrarily defined scale. Note: Choice is not an appropriate data type to use when the possible codes are defined as a value set from a formal code system or otherwise stored on a terminology server.
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <code value="[code]"/><!-- 0..1 Selected code --> <option> <!-- 1..* List of possible code values --> <code value="[code]"/><!-- 1..1 Possible code --> <display value="[string]"/><!-- 0..1 Display for the code --> </option> <isOrdered value="[boolean]"/><!-- 0..1 If order of the values has meaning --> </[name]>
The code is the selected value. A list of possible options for code must be provided; at least a code must be provided for each value. The selected code must be found in the list of possible codes.
If isOrdered is true, then the values have an inherent meaningful order and the list of values must be provided in the correct order in the instance.
A measured amount (or an amount that can potentially be measured).
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <value value="[decimal]"/><!-- 0..1 Numerical value (with implicit precision) --> <comparator value="[code]"/><!-- 0..1 Relationship of stated value to actual value --> <units value="[string]"/><!-- 0..1 Unit representation --> <system value="[uri]"/><!-- 0..1 System that defines coded unit form --> <code value="[code]"/><!-- 0..1 Coded form of the unit --> </[name]>
| Path | Definition | Type | Reference |
|---|---|---|---|
| Quantity.comparator | How the Quantity should be understood and represented | Fixed | http://hl7.org/fhir/quantity-comparator |
The value contains the numerical value of the quantity, including an implicit precision. If no comparator is specified, the value is a point value (i.e. '='). The comparator element can never be ignored.
The units element contains a displayable unit that defines what is measured. The units may additionally be coded in some formal way using the code and the system (see Coding for further information about how to use the system element).
If the units are able to be coded in UCUM and a code is provided, it SHOULD be a UCUM code. If a UCUM unit is provided in the code then a canonical value can be generated for purposes of comparison between quantities. Note that the units element will often contain text that is actually a valid UCUM unit, but it cannot be assumed that it does.
Constraints
The context of use may frequently define what kind of quantity this is and therefore what kind of units can be used. The context of use may additionally require a code from a particular system. The context of use may also restrict the values for the value or range.
These are used as types in resource content models, but they are really just a Quantity with some rules:
| Age | The unit must be an amount of time and a UCUM unit must be provided, and the value must be positive |
| Count | The value must a whole number and the UCUM unit must be "1" |
| Money | The unit must be a currency and the code must from ISO 4217 (system = "urn:std:iso:4217") |
| Distance | The unit must be an amount of length and a UCUM unit must be provided. |
| Duration | The unit must be an amount of time and a UCUM unit must be provided. |
A set of ordered Quantity values defined by a low and high limit.
A Range specifies a set of possible values; usually, one value from the range applies (e.g. "give the patient between 2 and 4 tablets"). Ranges are typically used in instructions.
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <low><!-- 0..1 Quantity Low limit --></low> <high><!-- 0..1 Quantity High limit --></high> </[name]>
The units and code/system elements of the low or high elements must match. If the low or high elements are missing, the meaning is that the low or high boundaries are not known and therefore neither is the range.
The range flag on the low or high elements cannot be present. Note that the Range type should not be used to represent out of range measurements: A quantity type with the comparator element should be used instead.
The low and the high values are inclusive, and are assumed to have arbitrarily high precision. E.g. the range 1.5 to 2.5 includes 1.50, and 2.50 but not 1.49 or 2.51.
Constraints
A ratio of two Quantity values - a numerator and a denominator.
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <numerator><!-- 0..1 Quantity The numerator --></numerator> <denominator><!-- 0..1 Quantity The denominator --></denominator> </[name]>
Common factors in the numerator and denominator are not automatically cancelled out. The Ratio data type is used for titers (e.g., "1:128") and other quantities produced by laboratories that truly represent ratios. Ratios are not simply "structured numerics" - for example blood pressure measurements (e.g. "120/60") are not ratios. In addition, ratios are used where common factors in the numerator and denominator do not cancel out. The most common example of this is where the ratio represents a unit cost, and the numerator is a currency (e.g. 50/$10).
Constraints
The context of use may require particular types of Quantity for the numerator or denominator.
A time period defined by a start and end time.
A period specifies a range of times. The context of use will specify whether the entire range applies (e.g. "the patient was an inpatient of the hospital for this time range") or one value from the period applies (e.g. "give to the patient between 2 and 4 pm").
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <start value="[dateTime]"/><!-- 0..1 The start of the period --> <end value="[dateTime]"/><!-- 0..1 The end of the period, if not ongoing --> </[name]>
If the start element is missing, the start of the period is not known. If the end element is missing, it means that the period is ongoing.
The end value includes any matching date/time. For example, the period 2011-05-23 to 2011-05-27 includes all the times of 23rd May through to the end of the 27th May.
Data that comes from a series of measurements taken by a device, with upper and lower limits. There may be more than one dimension in the data.
A SampledData provides a concise way to handle the data produced by devices that sample a physical particular state at a high frequency. A typical use for this is for the output of an ECG or EKG device.
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <origin><!-- 0..1 Quantity Zero value and units --></origin> <period value="[decimal]"/><!-- 0..1 Number of milliseconds between samples --> <factor value="[decimal]"/><!-- 0..1 Multiply data by this before adding to origin --> <lowerLimit value="[decimal]"/><!-- 0..1 Lower limit of detection --> <upperLimit value="[decimal]"/><!-- 0..1 Upper limit of detection --> <dimensions value="[integer]"/><!-- 0..1 Number of sample points at each time point --> <data value="[string]"/><!-- 0..1 Decimal values with spaces, or "E" | "U" | "L" --> </[name]>
The digits are a set of decimal values separated by a single space (Unicode character u20). In addition to decimal values, the special values "E" (error), "L" (below detection limit) and "U" (above detection limit) can also be used. If there is more than one dimension, the different dimensions are interlaced - all the data points for a particular time are represented together.
None of the elements in a SampledData are mandatory because the SampledData type is frequently used with devices where one usage carries just the data element, and the values of the other elements are represented elsewhere (see Device Log and Device Capabilities). At least one element must always be populated. The data is not interpretable without at least origin, period, and dimensions. When carried in an Observation, these 3 elements and data must be populated for the SampledData to be properly populated. The default value for factor is 1.
A logical identifier that is or can be used to identify an object or entity. Typically, identifiers are used to connect content in resources to external content available in other frameworks or protocols. Identifiers are associated with objects, and may be changed or retired due to human or system process and errors.
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <use value="[code]"/><!-- 0..1 The use of this identifier --> <label value="[string]"/><!-- 0..1 Description of identifier --> <system value="[uri]"/><!-- 0..1 The namespace for the identifier --> <key value="[string]"/><!-- 0..1 The value that is unique --> <period><!-- 0..1 Period Time period when id was valid for use --></period> <assigner><!-- 0..1 Resource(Organization) Organization that issued id (may be just text) --></assigner> </[name]>
| Path | Definition | Type | Reference |
|---|---|---|---|
| Identifier.use | Identifies the use for this identifier, if known | Fixed | http://hl7.org/fhir/identifier-use |
The system referred to by means of a URI defines how the identifier is defined (i.e. how the key value is made unique). It might be a specific application or a recognized standard/specification for a set or identifiers or a way of making identifiers unique. The key must be unique within the defined system and have a consistent meaning wherever it appears. Both system and key values are always case sensitive.
FHIR defines some useful URIs directly. OIDs (urn:oid:) and UUIDs (urn:uuid:) may be registered in the HL7 OID registry and should be if the content is shared or exchanged across institutional boundaries. If the identifier itself is naturally globally unique (i.e. an OID, a UUID, or a URI with no trailing local part), then the system must be "urn:ietf:rfc:3986", and the URI would be in the key.
In some cases, the system may not be known - only the key is known (e.g. a simple device that scans a barcode), or the system is known implicitly (simple exchange in a limited context, often driven by barcode readers). In this case, no useful matching may be performed using the key unless the system can be safely inferred by the context. This practice should be avoided where possible, as information sharing in a wider context is very likely to arise eventually, and key values without a system are inherently limited in value.
The assigner is used to indicate what registry/state/facility/etc. assigned the identifier.
A name of a human with text, parts and usage information.
Names may be changed or repudiated. People may have different names in different contexts. Names may be divided into parts of different type that have variable significance depending on context, though the division into parts does not always matter. With personal names, the different parts may or may not be imbued with some implicit meaning; various cultures associate different importance with the name parts and the degree to which systems must care about name parts around the world varies widely.
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <use value="[code]"/><!-- 0..1 The use of this name --> <text value="[string]"/><!-- 0..1 Text representation of the full name --> <family value="[string]"/><!-- 0..* Family name (often called 'Surname') --> <given value="[string]"/><!-- 0..* Given names (not always 'first'). Includes middle names --> <prefix value="[string]"/><!-- 0..* Parts that come before the name --> <suffix value="[string]"/><!-- 0..* Parts that come after the name --> <period><!-- 0..1 Period Time period when name was/is in use --></period> </[name]>
| Path | Definition | Type | Reference |
|---|---|---|---|
| HumanName.use | The use of a human name | Fixed | http://hl7.org/fhir/name-use |
The text element specifies the entire name as it should be represented. This may be provided instead of or as well as specific parts. Applications updating a name must ensure either that the text and the parts are in agreement, or that only one of the two is present.
Note that the order of the parts within a given part type has significance and must be observed. The appropriate order between family name and given names depends on culture and context of use.
vCard Mappings
A postal address. There are a variety of postal address formats defined around the world. Postal addresses are often also used to record a location that can be visited to find a patient or person.
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <use value="[code]"/><!-- 0..1 The use of this address --> <text value="[string]"/><!-- 0..1 Text representation of the address --> <line value="[string]"/><!-- 0..* Line of an address --> <city value="[string]"/><!-- 0..1 Name of city, town etc. --> <state value="[string]"/><!-- 0..1 Sub-unit of country (abreviations ok) --> <zip value="[string]"/><!-- 0..1 Post code for area --> <country value="[string]"/><!-- 0..1 Country (can be ISO 3166 3 letter code) --> <period><!-- 0..1 Period Time period when address was/is in use --></period> </[name]>
| Path | Definition | Type | Reference |
|---|---|---|---|
| Address.use | The use of an address | Fixed | http://hl7.org/fhir/address-use |
The text element specifies the entire address as it should be represented. This may be provided instead of or as well as the specific parts. Applications updating an address must ensure either that the text and the parts are in agreement, or that only one of the two is present.
Constraints
vCard Mappings
All kinds of technology-mediated contact details for a person or organization, including telephone, email, etc.
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <system value="[code]"/><!-- 0..1 Telecommunications form for contact --> <value value="[string]"/><!-- 0..1 The actual contact details --> <use value="[code]"/><!-- 0..1 How to use this address --> <period><!-- 0..1 Period Time period when the contact was/is in use --></period> </[name]>
| Path | Definition | Type | Reference |
|---|---|---|---|
| Contact.system | Telecommunications form for contact | Fixed | http://hl7.org/fhir/contact-system |
| Contact.use | Location, type or status of telecommunications address indicating use | Fixed | http://hl7.org/fhir/contact-use |
If capturing a phone, fax or similar contact, the value should be a properly formatted telephone number according to ITU-T E.123. However, this is frequently not possible due to legacy data and/or recording methods.
Constraints
A schedule that specifies an event that may occur multiple times. Schedules are not used for recording when things did happen, but when they are expected or requested to occur. A schedule can be either a list of events - periods on which the event occurs, or a single event with repeating criteria, or just repeating criteria with no actual event.
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <event><!-- 0..* Period When the event occurs --></event> <repeat> <!-- 0..1 Only if there is none or one event --> <frequency value="[integer]"/><!-- 0..1 Event occurs frequency times per duration --> <when value="[code]"/><!-- 0..1 Event occurs duration from common life event --> <duration value="[decimal]"/><!-- 1..1 Repeating or event-related duration --> <units value="[code]"/><!-- 1..1 The units of time for the duration --> <count value="[integer]"/><!-- 0..1 Number of times to repeat --> <end value="[dateTime]"/><!-- 0..1 When to stop repeats --> </repeat> </[name]>
| Path | Definition | Type | Reference |
|---|---|---|---|
| Schedule.repeat.when | Real world event that the schedule relates to | Fixed | http://hl7.org/fhir/event-timing |
| Schedule.repeat.units | A unit of time (units from UCUM) | Fixed | http://hl7.org/fhir/units-of-time |
If events are specified, at least event.start must be specified for each event. If no event.end is specified, the event is assumed to last a limited but unknown time as clinically relevant.
If the schedule has repeating criteria, the repeat can occur a given number of times per the specified duration or in relation to some real world event. Also, if the event repeats, a time to end the schedule can be specified, either by specifying a count number of times it can occur or a date at which to end the schedule. If no end condition is specified, the Schedule will terminate on some criteria that are expressed elsewhere.
Constraints
Some elements have no specified type. The type is represented by the wildcard symbol "*". In these cases, the element type may be one of the following:
The element name ends with "[x]", and this is replaced with the Title cased name of the data type.
The following types are defined as part of the data types, but are documented elsewhere in the specification: