Maturity Level: N/A | Standards Status:Informative |
This page provides the detailed descriptions for the data types
Table of Contents
Primitive Types | Complex Types |
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
See also Base Definition, Detailed Descriptions, Examples, Profiles & Extensions and Mappings.
Maturity Level: Normative | Standards Status:Partially Normative |
The FHIR specification defines a set of data types that are used for the resource elements. There are four categories of data types:
This page describes the general purpose data types (categories 1 and 2).
Data Types Summary.
Legend: see Standards Status Colors
A limited set of these data types may appear in extensions. All data types (including primitives) may have extensions, but only the following data types may include Modifier Extensions:
The following table describes the primitive types that are used in this specification. Primitive types are those with only a value, and no additional elements as children (though, like all types, they have extensions). See also the Examples.
Primitive Types | |||
FHIR Name | Value Domain | XML Representation | JSON representation |
---|---|---|---|
boolean | true | false | xs:boolean, except that 0 and 1 are not valid values | JSON boolean (true or false) |
Regex: true|false |
|||
integer | A signed integer in the range −2,147,483,648..2,147,483,647 (32-bit; for larger values, use decimal) | xs:int, except that leading 0 digits are not allowed | JSON number (with no decimal point) |
Regex: [0]|[-+]?[1-9][0-9]* |
|||
string | A sequence of Unicode characters | xs:string | JSON String |
Note that strings SHALL NOT exceed 1MB (1024*1024 characters) in size. Strings SHOULD not contain Unicode character points below 32, except for u0009 (horizontal tab), u0010 (carriage return) and u0013 (line feed). Leading and Trailing whitespace is allowed, but SHOULD be removed when using the XML format. Note: this means that a string that consists only of whitespace could be trimmed to nothing, which would be treated as an invalid element value. Therefore strings SHOULD always contain non-whitespace content | |||
This data type can be bound to a ValueSet | |||
Regex: [ \r\n\t\S]+ (see notes below) |
|||
decimal | Rational numbers that have a decimal representation. See below about the precision of the number | union of xs:decimal and xs:double (see below for limitations) | A JSON number (see below for limitations) |
Regex: -?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)? |
|||
uri | A Uniform Resource Identifier Reference (RFC 3986). Note: URIs are case sensitive. For UUID (urn:uuid:53fefa32-fcbb-4ff8-8a92-55ee120877b7) use all lowercase | xs:anyURI | A JSON string - a URI |
Regex: \S* (This regex is very permissive, but URIs must be valid. Implementers are welcome to use more specific regex statements for a URI in specific contexts) |
|||
URIs can be absolute or relative, and may have an optional fragment identifier This data type can be bound to a ValueSet |
|||
url | A Uniform Resource Locator (RFC 1738). Note URLs are accessed directly using the specified protocol. Common URL protocols are http{s}: , ftp: , mailto: and mllp: , though many others are defined |
xs:anyURI | A JSON string - a URL |
canonical | A URI that is refers to a resource by it's canonical URL (resources with a url property). The canonical type differs from a uri in that it has special meaning in this specification,
and in that it may have a version appended, separated by a vertical bar (|). Note that the type canonical is not used for the actual canonical URLs that are the target
of these references, but for the URIs that refer to them, and may have the version suffix in them. Like other URIs, elements of type canonical may also have #fragment references |
xs:anyURI | A JSON string - a canonical URL |
base64Binary | A stream of bytes, base64 encoded (RFC 4648) | xs:base64Binary | A JSON string - base64 content |
Regex: (\s*([0-9a-zA-Z\+\=]){4}\s*)+ |
|||
There is no specified upper limit to the size of a binary, but systems will have to impose some implementation based limit to the size they support. This should be clearly documented, though there is no computable for this at this time | |||
instant | An instant in time in the format YYYY-MM-DDThh:mm:ss.sss+zz:zz (e.g. 2015-02-07T13:28:17.239+02:00 or 2017-01-01T00:00:00Z). The time SHALL specified at least to the second and SHALL include a time zone.
Note: This is intended for when precisely observed times are required(typically system logs etc.), and not human-reported times - for those, use date or dateTime (which can be as precise as instant , but is not required to be). instant is a more constrained dateTime |
xs:dateTime | A JSON string - an xs:dateTime |
Note: This type is for system times, not human times (see date and dateTime below). | |||
Regex: ([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-9]000)-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])T([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00)) |
|||
date | A date, or partial date (e.g. just year or year + month) as used in human communication. The format is YYYY, YYYY-MM, or YYYY-MM-DD, e.g. 2018, 1973-06, or 1905-08-23. There SHALL be no time zone. Dates SHALL be valid dates | union of xs:date, xs:gYearMonth, xs:gYear | A JSON string - a union of xs:date, xs:gYearMonth, xs:gYear |
Regex: ([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-9]000)(-(0[1-9]|1[0-2])(-(0[1-9]|[1-2][0-9]|3[0-1]))?)? |
|||
dateTime | A date, date-time or partial date (e.g. just year or year + month) as used in human communication. The format is YYYY, YYYY-MM, YYYY-MM-DD or YYYY-MM-DDThh:mm:ss+zz:zz, e.g. 2018, 1973-06, 1905-08-23, 2015-02-07T13:28:17-05:00 or 2017-01-01T00:00:00.000Z. If hours and minutes are specified, a time zone SHALL be populated. Seconds must be provided due to schema type constraints but may be zero-filled and may be ignored at receiver discretion. Dates SHALL be valid dates. The time "24:00" is not allowed. Leap Seconds are allowed - see below | union of xs:dateTime, xs:date, xs:gYearMonth, xs:gYear | A JSON string - a union of xs:dateTime, xs:date, xs:gYearMonth, xs:gYear |
Regex: ([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-9]000)(-(0[1-9]|1[0-2])(-(0[1-9]|[1-2][0-9]|3[0-1])(T([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00)))?)?)? |
|||
time | A time during the day, in the format hh:mm:ss. There is no date specified. Seconds must be provided due to schema type constraints but may be zero-filled and may be ignored at receiver discretion. The time "24:00" SHALL NOT be used. A time zone SHALL NOT be present. Times can be converted to a Duration since midnight. | xs:time | A JSON string - an xs:time |
Regex: ([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)? |
|||
code | Indicates that the value is taken from a set of controlled strings defined elsewhere (see Using codes for further discussion). Technically, a code is restricted to 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 | xs:token | JSON string |
Regex: [^\s]+(\s[^\s]+)* This data type can be bound to a ValueSet |
|||
oid | An OID represented as a URI (RFC 3001); e.g. urn:oid:1.2.3.4.5 | xs:anyURI | JSON string - uri |
Regex: urn:oid:[0-2](\.(0|[1-9][0-9]*))+ |
|||
id | Any combination of upper or lower case ASCII letters ('A'..'Z', and 'a'..'z', numerals ('0'..'9'), '-' and '.', with a length limit of 64 characters. (This might be an integer, an un-prefixed OID, UUID or any other identifier pattern that meets these constraints.) | xs:string | JSON string |
Regex:
|
|||
markdown | A FHIR string (see above) that may contain markdown syntax for optional processing by a markdown presentation engine, in the GFM extension of CommonMark format (see below) |
xs:string | JSON string |
Regex: \s*(\S|\s)* (can't put size limit in the regex - too large) |
|||
unsignedInt | Any non-negative integer in the range 0..2,147,483,647 | xs:nonNegativeInteger | JSON number |
Regex: [0]|([1-9][0-9]*) |
|||
positiveInt | Any positive integer in the range 1..2,147,483,647 | xs:positiveInteger | JSON number |
Regex: +?[1-9][0-9]* |
|||
uuid | A UUID (aka GUID) represented as a URI (RFC 4122); e.g. urn:uuid:c757873d-ec9a-4326-a141-556f43239520 | xs:anyURI | JSON string - uri |
Notes:
INF
, -INF
and NaN
are not allowed, and JSON is restricted to the precision limits documented in XML schema for xs:double and xs:decimal[\r\n\t\x{0020}-\x{FFFF}]*
or [\r\n\t\u0020-\uFFFF]*
are better expressions of the constraints on string, but poorly supported (see Regex Tutorial for details).
The string
regex also applies to markdown
as well. The regex does not enforce the length limitcode
http://example.com/fhir/Patient/1234
, the last part "1234" (highlighted in red) is the part that is an id datatypeuri
, not an id
. UUIDs in URIs SHALL also be represented in lowercase (urn:uuid:59bf0ef4-e89c-4628-9b51-12ae3fdbe22b)uri
, url
and canonical
datatypes:
url
and canonical
are specializations of uri
, they are never substituted for each otherstring
, and subject to the same rules (e.g. length limit)string
to markdown
in a later version of this FHIR specification
is not considered a breaking change (neither is adding markdown
as a choice to an optional element that already has a choice of data types)All elements using these primitive types may have one or more of a value as described above, an internal identity (e.g. xml:id), and extensions. For an example, take an element of name "count" and type "integer".
XML
The value is represented in XML as an attribute named "value":
<count value="2"/>
The full representation, with id, extensions and value:
<count id="a1" value="2"> <extension url="..."> <valueXX.../> </extension> </count>
JSON
In JSON, for convenience, the value is represented as the property itself:
"count" : 2
The full representation, with id, extensions and value, showing the id and extensions in the sibling property:
"count" : 2 "_count" : { "id" : "a1", "extension" : [{ "url" : "...", "valueXXX" : "...." }] }
RDF
The value is represented in RDF as a relationship with the URI "http://h;7.org/fhir/value". Using the normal prefix, this becomes:
fhir:Type.count [ fhir:value "2"^^xsd:integer ]
For the types date and DateTime, the type must be specified explicitly. For all other types, it is optional. The full representation, with id, extensions and value:
fhir:Type.count [ Element.id "a1"; fhir:value "2"^^xsd:integer; Element.extension [ fhir:Extension.url ".."; fhir:Extension.valueXX... ] ]
For additional details, see the XML, JSON and Turtle format definitions. When the value is missing, and there are no extensions, the element is not represented at all. This means that in xml, attributes are never present with a length of 0 (value=""), and properties are never a 0 length string or null in JSON ("name" : "" is not valid). (note: there is one specific use of the null in the JSON representation).
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. In JSON and Turtle whitespace in string values is always significant. Primitive types other than string SHALL NOT have leading or trailing whitespace.
In XML, 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. In JSON, the data type is represented by an object with properties named the same as the XML elements. Since the JSON representation is almost exactly the same, only the first example has an additional explicit JSON representation.
Complex data types may be "profiled". A Structure Definition or type "constraint" makes a set of rules about which elements SHALL have values and what the possible values are.
UML Diagrams of the Data types
See also Examples, Detailed Descriptions, Mappings, Profiles & Extensions and R2 Conversions.
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.
The actual content of an Attachment can be conveyed directly using the data
element
or a URL
reference can be provided. If both are provided, the reference SHALL
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 SHALL
point to a location that resolves to actual data; some URIs such as cid: meet this requirement.
If the URL is a relative reference, it is interpreted in the same way as a resource reference.
The contentType
element SHALL always be populated when an Attachment contains data
, and
MAY be populated when there is a url
. 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 hash
is included so that applications can verify that the content returned by the URL has not changed. The hash
and size
relate to the data before it is represented in base64 form. The hash is not intended to support digital signatures.
Where protection against malicious threats a digital signature should be considered, see
Provenance.signature for mechanism to protect a resource with a digital signature.
Attachment data
are not constrained, and therefore can be of any content type and encoding.
Therefore extra care needs to be taken to validate the content against
malicious or malformed content. For more details see Security of Narrative.
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 SHALL 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 language
is available for the combination of language
and contentType
.
The context of use may frequently make rules about the kind of attachment (and therefore, the kind of mime types) that can be used.
Attachment is used in the following places:
See also Examples, Detailed Descriptions, Mappings, Profiles & Extensions and R2 Conversions.
A Coding is a representation of a defined concept using a symbol from a defined "code system" - see Using Codes in resources for more details.
This data type can be bound to a ValueSet.
The meaning of the Coding is defined by the code. The system
provides
the source of the definition of the code, along with an optional version reference.
The display is a human display for the text defined by the system - it is not intended
for computation.
The system
is a URI that identifies the code system that defines the code
.
Choosing the correct system is important; for more information about the code system
URI, read Managing Terminology System URIs.
If the code is taken from a CodeSystem resource, CodeSystem.url
is the
correct value for the system element. Resolvable URLs are generally preferred by
implementers over non-resolvable URNs, particularly opaque URNs such as OIDs (urn:oid:)
or UUIDs (urn:uuid:). The system URI SHALL NOT contain a reference to a value set
(e.g. ValueSet.url
), since value sets just define the set of codes
which are intended for use in a specific context, not the meaning of the codes themselves.
A code system version may also be supplied. If the meaning of codes within the code system is consistent across releases, this is not required. The version SHOULD be exchanged when the system does not maintain consistent definitions across versions. Note that the following systems SHOULD always have a version specified:
More generally, any classification (e.g. a code system that includes concepts with relative definitions such as "not otherwise coded" will require a version. See the discussion of code system versions in the Code System resource for further discussion on versioning.
If present, the code
SHALL be a syntactically correct symbol as defined by the system
.
In some code systems such as SNOMED CT, the symbol may be an expression composed of other predefined symbol (e.g. post-coordination).
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 is used to display
the meaning of the code by an application that is not aware of the system
.
If the 'display' element is populated, the string used in display
SHALL be one of the display strings defined for
that code by the code system (code systems may define multiple display strings for a single code).
If one of the available display strings is labeled as preferred, it SHOULD be used. If the code system does not define a text representation
for display (e.g. SNOMED CT Expressions) then the 'display' element cannot be populated, and the meaning of the code won't be
accessible to systems that don't understand the code expression.
In some cases, the system
might 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
, version
and code
then they have the same meaning.
If the version information is missing, or the system
, version
or the code
elements differ, then
how the codes are related can only be determined by consulting the definitions of the system(s) and any mappings available.
A coding may be marked as a "userSelected" if a user selected the particular coded value in a user interface (e.g. the user selects an item in a pick-list). If a user selected coding exists, it is the preferred choice for performing translations etc.
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.
Coding is used in the following places:
This specification defines two types for representing coded values:
The Coding
data type corresponds to the simple case of selecting
a single code from a code list. However this type is rarely used in the
FHIR specifications; long experience with exchanging coded values in
HL7 shows that in the general case, systems need to able to exchange
multiple translation codes, and/or an original text.
The Coding
data type is used directly when there is certainty that the value
must be selected directly from one of the available codes, and the list of
possible codes is agreed to by all participants. This is not usually the case
in the context of FHIR - general interoperability - so Coding is mostly used
in extensions, which are usually intended to be defined for a well-controlled context of use.
See also Examples, Detailed Descriptions, Mappings, Profiles & Extensions and R2 Conversions.
A CodeableConcept represents a value that is usually supplied by providing a 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.
This data type can be bound to a ValueSet.
Additional Codes
More than one code may be used in CodeableConcept
. 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). Each coding
(also referred to as a 'translation') is a representation of the concept as described above and may have slightly different granularity due to the differences
in the definitions of the underlying codes. There is no meaning associated with the ordering of coding
within a CodeableConcept
.
A typical use of CodeableConcept
is to send the local code that the concept was coded with, and also one or more translations to publicly defined
code systems such as LOINC or SNOMED CT. Sending local codes is useful and important for the purposes of debugging and integrity auditing.
For example many qualitative laboratory test results values are typically represented with coded presence/absence concepts. Using the coded value for 'negative' with a standard SNOMED CT code translation, valueCodeableConcept
would be:
"valueCodeableConcept": { "coding": [ { "system": "http://snomed.info/sct", "code": "260385009", "display": "Negative" }, { "system": "https://acme.lab/resultcodes", "code": "NEG", "display": "Negative" } ], "text": "Negative for Chlamydia Trachomatis rRNA" }
Note that these concepts may be cross mapped using the ConceptMap resource instead of or in addition to being represented as translations directly in the in CodeableConcept
.
Using Text in CodeableConcept
The text
is the representation of the concept as entered or chosen by the user, and 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 or more of the codings
may be flagged as the user selected code - the code or concept that the user actually selected directly.
Note that in all but a few cases, only one of the codings may be flagged as the coding.userSelected = true
- the code or concept that the user actually selected directly. If more than one code is marked as user selected,
this means the user explicitly chose multiple codes. When none of the coding
elements is
marked as user selected, the text (if present)is the preferred source of meaning.
A free text only representation of the concept without any coding
elements is permitted if there is no appropriate code and only free text is available (and not prohibited by the implementation). For example using text only, the Observation.valueCodeableConcept
element would be:
"valueCodeableConcept": { "text": "uncoded free text result" }
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.
CodeableConcept is used in the following places:
See also Examples, Detailed Descriptions and Mappings, Profiles & Extensions and R2 Conversions.
A measured amount (or an amount that can potentially be measured).
This data type can be bound to a ValueSet.
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 unit
element contains a displayable unit that defines what is measured.
The unit 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 unit can 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 unit
element will often
contain text that is a valid UCUM unit, but it cannot be assumed that the unit actually contains a valid UCUM unit.
Constraints
The context of use may frequently define what kind of measured quantity
this is and therefore what kind of unit can be used. The context
of use may additionally require a code
from a particular system
, or a value set
- see
Using Terminologies for information about binding a Quantity to a value set to constrain the unit codes.
The context of use may also restrict the values for the value
or comparator
.
Quantity is used in the following places:
There are several additional data types that are specializations of Quantity that only introduce new restrictions on the existing elements defined as part of the Quantity data type.
The types Age, Distance and Count are marked as Trial Use because they are not used in this specification (though they may be used in extensions). These types may be converted back to a profile (see R2 definitions).
Type Name | Rules | Formal Definitions |
Distance | XML, JSON | |
Usage: | ||
If the duration value is specified as a whole number (e.g. 1 month), then when the duration is added or subtracted to a given date(time), the outcome should be rounded to the nearest natural calendar division - e.g. Feb. 1 + 1 mo = March 1, not March 2 or 3 (since 1 month in is defined in UCUM as 30 days). | ||
Age | XML, JSON | |
Usage: | ||
Count | XML, JSON | |
Usage: | ||
Duration | XML, JSON | |
Usage: | ||
In addition to the specializations, there is one constraint on Quantity used in several resources: |
||
Profile Name | Rules | Formal Definitions |
Simple Quantity | XML, JSON | |
Usage: |
Note that the constraint is different from the other specializations of Quantity because it is not a type, just rules applied where the Quantity type is used. There's another constraint - see Money immediately below.
See also Examples, Detailed Descriptions and Mappings, Profiles & Extensions and R2 Conversions.
An amount of currency.
The value
contains the amount of the currency, including an implicit precision.
Precision is always important for financial amounts. The currency
element
contains an ISO 4217 code for the currency.
Money is used in the following places:
There are also circumstances where a financial amount must be represented as
the numerator or denominater in a Ratio, where the type is currency. In this context,
the Money amount is represented as a Quantity, using the
MoneyQuantity
constraint:
Profile Name | Rules | Formal Definitions |
Money Quantity | XML, JSON | |
Usage: |
Note that the profile is different from the other specializations because it is not a type, just rules applied where the Quantity type is used to represent Money amounts.
See also Examples, Detailed Descriptions, Mappings, Profiles & Extensions and R2 Conversions.
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.
The unit
and code
/system
elements of the low
or high
elements SHALL 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 complete range.
The comparator
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
Range is used in the following places:
See also Examples, Detailed Descriptions, Mappings, Profiles & Extensions and R2 Conversions.
A relationship between two Quantity values expressed as a numerator and a denominator.
The Ratio datatype should only be used to express a relationship of two numbers if the relationship cannot be suitably expressed using a Quantity and a common unit. Where the denominator value is known to be fixed to "1", Quantity should be used instead of Ratio.
Examples where a Quantity is typically used are rates, densities, concentrations. Examples where a Ratio is used are: titers (e.g. 1:128); concentration ratios where the denominator is significant (e.g. 5mg/10mL); observed frequencies (e.g. 2 repetitions/8 hr), and where the numerator or denominator is an amount of a currency (no UCUM code for $ etc.).
Common factors in the numerator and denominator are not automatically cancelled out. Ratios are not simply "structured numbers" - for example blood pressure measurements (e.g. "120/60") are not ratios.
A proper ratio has both a numerator and a denominator; however these are not mandatory in order to allow an invalid ratio with an extension with further information.
Constraints
The context of use may require particular types of Quantity for the numerator or denominator.
Ratio is used in the following places:
See also Examples, Detailed Descriptions, Mappings, Profiles & Extensions and R2 Conversions.
A time period defined by a start and end date/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 on 24-Jun 2013").
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,
or the start may be in the past, and the end date in the future, which means that period
is expected/planned to end at the specified time
The end value includes any matching date/time. For example, the period 2011-05-23 to 2011-05-27 includes all the times from the start of the 23rd May through to the end of the 27th of May.
Period is used in the following places:
See also Examples, Detailed Descriptions, Mappings, Profiles & Extensions and R2 Conversions.
Data that comes from a series of measurements taken by a device, which may have upper and lower limits. The data type also supports more than one dimension in the data.
A SampledData provides a concise way to handle the data produced by devices that sample a particular physical state at a high frequency. A typical use for this is for the output of an ECG or EKG device. The data type includes a series of raw decimal values (which are mostly simple integers), along with adjustments for scale and factor. These are interpreted such that
original measured value[i] = SampledData.data[i] * SampledData.scaleFactor + SampledData.origin.value
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.
SampledData is used in the following places:
See also Examples, Detailed Descriptions, Mappings, Profiles & Extensions and R2 Conversions.
A numeric or alphanumeric string that is associated with a single object or entity within a given system. 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.
The value
SHALL be unique within the defined system
and have a consistent meaning wherever it appears. Identifier.system is always case sensitive. Identifier.value
is
to be treated as case sensitive unless knowledge of the Identifier.system
allows the processer to be confident
that non-case-sensitive processing is safe.
The system
is a URI that defines a set of identifiers (i.e. how the value
is made unique).
It might be a specific application or a recognized standard/specification for a set of identifiers
or a way of making identifiers unique.
FHIR defines some useful or important system URIs directly. Here are some
example identifier namespaces:
http://hl7.org/fhir/sid/us-ssn
for United States Social Security Number (SSN) valueshttp://ns.electronichealth.net.au/id/hi/ihi/1.0
for Australian Individual Healthcare Identifier (IHI) numbersurn:ietf:rfc:3986
for when the value of the identifier is itself a globally unique URIIf the system is a URL, it SHOULD resolve. Resolution might be to a web page that describes the identifier system and/or supports look-up of identifiers. Alternatively, it could be to a NamingSystem resource instance. Resolvable URLs are generally preferred by implementers over non-resolvable URNs, particularly opaque URNs such as OIDs (urn:oid:) or UUIDs (urn:uuid:). If used, OIDs and UUIDs may be registered in the HL7 OID registry and SHOULD be registered if the content is shared or exchanged across institutional boundaries.
It is up to the implementer organization to determine an appropriate URL or URN structure that will avoid collisions and to manage that space (and the resolvability of URLs) over time.
Note that the scope of a given identifier system may extend beyond identifiers that might be captured by a single resource. For example, some systems might draw all "order" identifiers from a single namespace, though some might be used on MedicationRequest while others would appear on ServiceRequest.
If the identifier value itself is naturally a globally unique URI (e.g. an OID, a UUID, or a URI with no trailing local part),
then the system
SHALL be "urn:ietf:rfc:3986
", and the URI is in the value
(OIDs and UUIDs using urn:oid: and urn:uuid: - see note on the V3 mapping and the examples).
In some cases, the system might not be known - only the value 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 value unless the system can be safely inferred by the
context. Applications should provide a system
wherever possible, as information sharing in a wider context
is very likely to arise eventually, and values without a system are inherently limited in use.
In addition to the system
(which provides a uniqueness scope) and the value
, identifiers may also have a
type
, which may be useful when a system encounters identifiers with unknown system values.
Note, however, that the type of an identifier is not a well-controlled vocabulary with wide variations
in practice. The type
deals only with general categories of identifiers and SHOULD not be
used for codes that correspond 1..1 with the Identifier.system. Some identifiers may fall into multiple
categories due to variations in common usage.
The assigner
is used to indicate what registry/state/facility/etc. assigned the identifier.
As a Reference, the assigner can include just a text description in the display
.
Constraints
Identifier is used in the following places:
See also Examples, Detailed Descriptions, Mappings, Profiles & Extensions and R2 Conversions.
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 is not always significant. With personal names, the different parts might or might not be imbued with some implicit meaning; various cultures associate different importance with the name parts and the degree to which systems SHALL care about name parts around the world varies widely.
This table summarizes where common parts of a person's name are found.
Name | Example | Destination / Comments |
Surname | Smith | Family Name |
First name | John | Given Name |
Title | Mr | Prefix |
Middle Name | Samuel | Subsequent Given Names |
Patronymic | bin Osman | Family Name |
Multiple family names | Carreño Quiñones | Family Name. See note below about decomposition of family name |
Initials | Q. | Given Name as initial ("." recommended) |
Nick Name | Jock | Given name, with Use = common |
Qualifications | PhD | Suffix |
Honorifics | Senior | Suffix |
Voorvoegsel / Nobility | van Beethoven | Family Name. See note below about decomposition of family name |
For further information, including all W3C International Examples, consult the examples. Note: Implementers should read the name examples for a full understanding of how name works.
The multiple given parts and family name combine to form a single name.
Where a person has alternate names that may be used in place of each other (e.g. Nicknames, Aliases),
these are different instances of HumanName
.
The text element specifies the entire name as it should be displayed e.g. in an application UI. This may be provided instead of or as well as the specific parts. Applications updating a name SHALL ensure that when both text and parts are present, no content is included in the text that isn't found in a part. The correct order of assembly of the parts is culture dependent: the order of the parts within a given part type has significance and SHALL be observed. The appropriate order between family name and given names depends on culture and context of use. Note that there is an extension for the few times name assembly order is not fixed by the culture.
The given name parts may contain whitespace, though generally they don't. Initials may be used in place of the full name if that is all that is recorded. Systems that operate across cultures should generally rely on the text form for presentation and use the parts for index/search functionality. For this reason, applications SHOULD populate the text element for future robustness.
In some cultures (e.g. German, Dutch, Spanish, Portuguese), family names are complex and composed of
various parts that may need to be managed separately, e.g. they have differing significance
for searching. In these cases, the full family name is populated in family
,
and a decomposition of the name can be provided using the family
extensions
own-name,
own-prefix,
partner-name,
partner-prefix,
fathers-family and
mothers-family.
For robust search, servers should search the parts of a family name independently. E.g. Searching either Carreno or Quinones should match a family name of "Carreno Quinones". HL7 affiliates, and others producing implementation guides, may make more specific recommendations about how search should work in specific cultures or environments.
Constraints
HumanName is used in the following places:
See also Examples, Detailed Descriptions, Mappings, Profiles & Extensions and R2 Conversions.
An address expressed using postal conventions (as opposed to GPS or other location definition formats). This data type may be used to convey addresses for use in delivering mail as well as for visiting locations which might not be valid for mail delivery. There are a variety of postal address formats defined around the world.
The text element specifies the entire address as it should be displayed e.g. on a postal label. This may be provided instead of or as well as the specific parts. Applications updating an address SHALL ensure that when both text and parts are present, no content is included in the text that isn't found in a part.
Constraints
Address is used in the following places:
See also Examples, Detailed Descriptions, Mappings, Profiles & Extensions and R2 Conversions.
Details for all kinds of technology-mediated contact points for a person or organization, including telephone, email, etc.
If capturing a phone, fax or similar contact point, 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 clerical practices when recording contact details.
For this reason, phone, fax, pager, and email addresses are not handled as formal URLs. For other kinds
of contact points, the system
is "other" and the value
SHOULD be a URL so that its use can be determined automatically. Typical
URL schemes used in the value are http{s}: for web addresses, and URL schemes for various kinds of messaging systems.
If the value is not a URL, then human interpretation will be required.
The rank
element can be used to specify a preference for the order in which a set of contacts
is used. ContactPoints with lower rank values are more preferred than those with higher rank values. Note that rank
does not necessarily
follow the order in which the contacts are represented in the instance.
Constraints
ContactPoint is used in the following places:
See also Examples, Detailed Descriptions, Mappings, Profiles & Extensions and R2 Conversions.
Describes the occurrence of an event that may occur multiple times. Timing schedules are used for specifying when events are expected or requested to occur and may also be used to represent the summary of a past or ongoing event. For simplicity, the definitions of Timing components are expressed as 'future' events, but such components can also be used to describe historic or ongoing events.
A Timing schedule can be a list of events and/or criteria for when the event happens, which can be expressed in a structured form and/or as a code. When both event and a repeating specification are provided, the list of events should be understood as an interpretation of the information in the repeat structure.
Note: the Timing data type allows modifier extensions.
If the timing schedule has repeating criteria, the repeat can occur a given number of times per the specified duration or in relation to some repeating real-world event. If no end condition is specified, the schedule will terminate on some criteria that are expressed elsewhere.
This table summarizes some common uses of the Timing Data Type criteria.
description | duration | durationUnit | frequency | frequencyMax | period | periodUnit | periodMax | Day of Week | Time Of Day | when | offset | bounds[x] | count |
Every 8 hours | 1 | 8 | h | ||||||||||
Every 7 days | 1 | 7 | d | ||||||||||
3 times a day | 3 | 1 | d | ||||||||||
3-4 times a day | 3 | 4 | 1 | d | |||||||||
Every 4-6 hours | 1 | 4 | h | 6 | |||||||||
Every 21 days for 1 hour | 1 | hr | 1 | 21 | d | ||||||||
Three times a week for ½ hour | 0.5 | hr | 3 | 1 | wk | ||||||||
With breakfast | CM | ||||||||||||
For 5 minutes, 10 minutes before meals | 5 | min | AC | 10 | |||||||||
1 tablet 3 times daily, 30 minutes before meals | 3 | 1 | d | AC | 30 | ||||||||
BID, 30 mins before meal, for next 10 days | 2 | 1 | d | AC | 30 | Duration = 10 days | |||||||
TID, for 14 days | 3 | 1 | d | Duration = 14 days | |||||||||
BID, start on 7/1/2015 at 1:00 PM | 2 | 1 | d | Period.start = 2015-07-01T13:00:00 | |||||||||
Mon, Wed, Fri Morning | 1 | 1 | d | mon | wed | fri | MORN | ||||||||
Every day at 10am | 1 | 1 | d | 10:00 | |||||||||
Take once, at any time | 1 | ||||||||||||
Take every second day, in the morning, until 20 have been taken | 1 | 2 | d | MORN | 20 |
Many systems avoid the complexity of the Timing structure by using a text field for timing instructions.
This maps to Timing.code.text
. For example, the text instruction "take medication in
the morning on weekends and days off work' would be represented as:
"timing": { "code" : { "text" : "Take medication in the morning on weekends and days off work" } }
Note, though, that some systems include timing details in
something like 'Dosage instructions' which is wider than just Timing; those systems do not use the
Timing data type. Other systems use a set of 'common' codes - including, but usually not limited to,
widely understood acronyms such as "BID". If a Timing.code
is
provided, the code is understood to be a complete statement of whatever is specified in the structured timing
data (except for Timing.repeat.bounds
, which applies to the code), and either the code or the
data may be used to interpret the Timing
. A structured timing specification SHOULD be provided whenever
possible, unless the code is BID, TID, QID, AM or PM, which have a ubiquitous meaning.
This table shows the relationship between the codes provided as part of the base specification, and the structured data portions of the Timing type:
description | duration | durationUnit | frequency | frequencyMax | period | periodUnit | periodMax | when | bounds[x] |
QOD | 1 | 2 | d | ||||||
QD | 1 | 1 | d | ||||||
BID | 2 | 1 | d | ||||||
TID | 3 | 1 | d | ||||||
QID | 4 | 1 | d | ||||||
Q4H | 1 | 4 | h | ||||||
Q6H | 1 | 6 | h | ||||||
AM | 1 | 1 | d | MORN | |||||
PM | 1 | 1 | d | AFT or EVE |
These codes SHALL be understood as having the formal meanings documented in this table. Note that BID, etc. are defined as 'at institutionally specified times'.
For example, an institution may choose that BID is "always at 7am and 6pm". If it is inappropriate for this choice to be made, the code BID
should not be used. Instead, a distinct organization-specific code should be used in place of the HL7-defined BID code and/or a structured
representation should be used (in this case, timeOfDay
).
Constraints
Note that these constraints still allow for nonsensical timing specifications such as "Once per day at 2:00 and 4:00" or "every 3 days on Friday".
Implementers must take care to ensure that their configuration and data collection designs do not lead to these non-interpretable timing specifications.
The elements dayOfWeek
, timeOfDay
, and when
are particularly likely to be at issue here.
Timing is used in the following places:
See also Examples, Detailed Descriptions, Mappings, Profiles & Extensions and R2 Conversions.
A Signature holds an electronic representation of a signature and its supporting context in a FHIR accessible form. The signature may either be a cryptographic type (XML DigSig or a JWS), which is able to provide non-repudiation proof, or it may be a graphical image that represents a signature or a signature process.
Constraints
Note: One consequence of signing the document is that URLs, identifiers and internal references are frozen and cannot be changed. This might be a desired feature, but it may also cripple interoperability between closed ecosystems where re-identification frequently occurs. For this reason, it is recommended that systems consider carefully the impact of any signature processes. The impact of signatures on Document bundles and their related processes is the most well understood use of digital signatures.
When the signature is an XML Digital Signature (contentType = application/signature+xml), the following rules apply:
Signature.type
shall contain the same values as the CommitmentTypeIndication element.There are three levels of signature verification:
Deviations from these guidelines would need to be expressed in site policy and would be enumerated in the XML-Signature block. For example, some environments may choose a different XAdES profile, hashing algorithm, policy identifier, or signature purpose vocabulary.
When the signature is an JSON Digital Signature (contentType = application/jose), the following rules apply:
Signature.type
shall contain the same values as the CommitmentTypeIndication element.There are three levels of signature verification:
Deviations from these guidelines would need to be expressed in site policy and would be enumerated in the JWS-Signature block. For example, some environments may choose a different hashing algorithm, policy identifier, or signature purpose vocabulary.
Signature is used in the following places:
See also Examples, Detailed Descriptions, Mappings, Profiles & Extensions and R2 Conversions.
A text note which also contains information about who made the statement and when.
Systems that do not have structured annotations simply communicate a single annotation with no author or time.
This element may need to be included in narrative because of the potential for modifying information.
Annotations SHOULD NOT be used to communicate "modifying" information that could be computable (this is a SHOULD because enforcing user behavior is nearly impossible).
Annotation is used in the following places:
Some elements do not have a 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.
Open references are used in the following places:
The following types are defined as part of the data types, but are documented elsewhere in the specification:
Maturity Level: 3 | Standards Status:Normative |
All extensions used in resources require a formal published definition that can be used by application developers or the applications themselves, to help integrate extensions into the healthcare process they support.
Every extension in a resource refers directly to its definition, which is made available as a StructureDefinition. A resource can be profiled to to specify where particular extensions are required or expected.
Whenever resources containing extensions are exchanged, the definitions of the extensions
SHALL be available to all the parties that share the resources. Each extension contains a
URI that references the source of the definitions as a StructureDefinition. The source SHOULD
be a literal reference, such as an http: URL that refers to an end-point that responds with
the contents of the definitions - preferably a FHIR RESTful server
supporting the StructureDefinition
, or a logical reference (e.g. using a urn:) - for instance,
to a national published standard.
Extensions may be defined by any project or jurisdiction, up to and including international standards organizations such as HL7 itself.
Before defining a new extension, attempt to reuse existing extensions defined in one of the shared registries described below. Also consider that some concepts may be appropriate to add as part of the core specification.
See also Best Practice Guidance for defining extensions.
Elements are included as part of FHIR resources and data types principally on the basis of current world-wide usage patterns. Policy is that if a significant majority of systems throughout the world that would use a resource or data type would use an element, then that element will be included as part of the resource/data type. If not, it will be left to an extension. This holds even if the element is very common or even mandatory in one or two specific jurisdictions.
Proposals suggesting a new core element can be raised by anyone. (Free registration is required.) However, given the timelines for new FHIR releases as well as the uncertainties associated with vetting the specification through a ballot process, it may still be necessary to define extensions even for elements that are likely to be supported as part of the core specification in a future release.
Extensions are always defined against some particular context - which elements they can extend. There are three different ways to specify which elements an extension can be found on:
Code | Context type | Context format | Examples |
---|---|---|---|
fhirpath | A FHIRPath expression that selects the set of elements on which the extension can appear | The FHIRPath statement always starts from the root of the resource that might contain the element | Condition (Condition | Observation).code |
element | Formal Element Id for the element | Element Ids are unique within the base specification, and within a structure definition. The full path for the element is [url]#[elementid]. If there is no #, the Element id is one defined in the base specification | Address.part.value http://hl7.org/fhir/StructureDefinition/resprate#Observation.category:vscat.coding |
extension | Another extension | The canonical URL of the extension, optionally followed by #code for extension that appear within a complex extension | http://hl7.org/fhir/StructureDefinition/device-din |
Extensions SHALL only be used on a target that appears in their context list.
The cardinality constraints asserted by the extension definition itself apply to any contexts where the extension is used.
Minimum Cardinality
If the Extension minimum cardinality is 0, then the extension is, by default, optional anywhere it appears. A profile that defines the use of an extension may make the minimum cardinality any number up to the maximum cardinality of the extension itself. Example: Patient birthplace.
If the Extension minimum cardinality is > 1, then the extension must have a minimum cardinality of at least the minimum cardinality in any profile that defines the use of the extension. The minimum cardinality may be any number up to the maximum cardinality of the extension. Even with a minimum cardinality > 0, the extension is only required to be present in instances if the instances explicitly or implicitly conform to a profile that defines the use of the extension. Example: CapabilityStatement Expectation.
Maximum Cardinality
If the Extension maximum cardinality is 1, then the extension is only allowed once on any element on which it appears. A profile that defines the use of an extension can only make the maximum cardinality 1 (or zero if the minimum cardinality is 0, and the profile constrains another profile that allows the extension). Example: Mother's Maiden Name.
If the Extension maximum cardinality is >1, then the extension is allowed up to the specified number of times on any element on which it appears. A profile that defines the use of an extension may make the maximum cardinality any value up to the specified maximum. Example: Patient Disability.
Context Invariants
Extensions are also able to define context invariants, which is a rule that is executed on the element that contains the extension when it is present to check that local requirements around cardinality and other business rules are met.
For example, if you use the extension for house number, the Address.line needs to be filled as well:
<contextInvariant value="line.exists()"/>
Note that since the context invariant is only evaluated when the extension is present, there is an implicit
"line.extension('http://hl7.org/fhir/StructureDefinition/iso21090-ADXP-streetName').exists() implies"
at
the start of the expression. A context invariant that enforces that the extension is present under certain
circumstances cannot be defined in the extension itself - it must be defined in a profile that makes use
of the extension.
An extension is a wrapper for an identifying url and either a value or other extensions. As such,
some of the properties of the extension are defined on the extension
itself, while others are defined on the Extension.value
. This
list provides guidance for the correct usage:
url
Note: Extensions are always sliced by their url
property. Re-slicing extensions by
additional properties is allowed (see Profiling/Slicing).
As well as defining the base element structure for resources, HL7 also publishes extensions, including as part of this specification. HL7 publishes such data definitions as extensions rather than as part of the base resource structure to keep the base resource structure simple and concise, and to allow implementers freedom from needing to engage with an entire world's worth of functionality up front.
Before extensions can be used in instances, their definition SHALL be published. HL7 maintains two extension registries:
Users are encouraged to register their extensions in the second registry, though this is not required. All that is required is that the extension is published in a context that is available for users of the extension. So, for example, if a particular extension is only used within a single institution, the definition of the extension can be placed on the institution's intranet. However since, by their nature, resources tend to travel well, it's always better to publish it on a public facing web site. Using the FHIR registry or other publicly accessible extension registries not only publishes the extension, but makes it easy to find and encourages reuse and therefore consistency across implementations.
The HL7 FHIR registry can be found at http://hl7.org/fhir/registry.
HL7 extension definitions may be balloted alongside resource content as part of the FHIR specification or may be published as part of separate specifications. When HL7 publishes extension definitions as part of the FHIR specification, these extensions SHALL be used for this data whenever the data is represented in instances. Applications SHOULD use other HL7-defined extensions published to represent equivalent data in the interest of maximum interoperability.
To minimize complexity for implementers, HL7 will not elevate widely adopted extensions (defined by HL7 or other organizations) to be content defined in a core resource in future versions of the resource unless there is widespread endorsement of such a migration from the implementer community. This policy ensures that widespread adoption of an extension does not result in a forced migration to a core element. Extensions labeled as draft may be moved in either direction, but after extensions are finalized as normative they won't be moved.
In some cases, an HL7 work group or other body may publish a profile whose sole purpose is to define extensions expected to be needed by implementers in a particular context; e.g. extensions needed to map a particular set of HL7 v2 segments or a HL7 v3 model.
Implementations are encouraged to share their extensions with HL7 and register them with the HL7 extension registry. The domain committees will work to elevate the extensions into HL7 published extensions or, if adopted by a broad enough portion of the implementer community, into the base resource structure itself.
To avoid interoperability issues, extensions SHALL NOT change their definition once published. (Small clarifications to descriptions that do not affect interoperability are permitted.) Rather than modifying an existing extension, a new extension should be introduced. Revisions to an extension may extend the set of contexts in which the extension apply but SHALL NOT remove or constrain any context previously listed
Work Group Standards Status:Informative |
The Diagnostics Module provides an overview and guide to the FHIR content that addresses ordering and reporting of clinical diagnostics including laboratory testing, imaging and genomics.
The Diagnostics module covers the following resources:
The diagnostic resources and their relationships are shown below. The arrows represent the direction of the references between resources (for example, DiagnosticReport references ServiceRequest). See the Workflow Module for information about the coordination of activities such as ordering and fulfilling of diagnostics.
Name | Aliases | Description |
The diagnostic resources often represent patient-specific data, and as such are susceptible to data breaching. Necessary privacy and security provisions must be in place when searching and fetching this information. For more general considerations, see the Security and Privacy module.
Diagnostic resources are commonly used to plan, recommend, order and report clinical diagnostics:
There are many ways to use these resources independently as well. The Observation resource in particular is central to capturing many measurements and events in healthcare and is often used outside the context of diagnostic orders and reports.
The resources that represent the basic information about a patient and a clinical encounter can be found in the Administration Module. Other resources that represent core clinical information generated by healthcare providers during the course of a patient encounter are detailed in the Clinical Summary Module and the Medications Module.
Maturity Level: N/A | Standards Status:Informative |
This is an automatically generated list of all the structural differences between FHIR DSTU3 and this version. The following possible changes are checked when preparing this list (and others throughout the specification):
This analysis only considers changes to data types and resources. Comparison of extensions, profiles and value sets will be added in a future version.
See also the version transforms and the note about version specific extensions.
The following versions of FHIR are available:
Date | Version | Description |
Current Versions | ||
Sept 30, 2014 | 0.0.82 | Current Official Published Version (Currently: DSTU1 + 2 technical errata) |
(current) | (last commit) | Current Development build (about 40min behind version control, may be incoherent and change rapidly) |
DSTU 2 sequence | ||
August 31, 2015 | 1.0.0 | DSTU 2 QA Preview + CQIF Ballot (Sep 2015) |
April 2, 2015 | 1.0.0 | DSTU 2 Ballot version (May 2015 Ballot) |
Dec 12, 2014 | 0.4.0 | Draft For Comment (January 2015 Ballot) |
DSTU 1 sequence | ||
Sept 30, 2014 | 0.0.82 | DSTU 1 (Official version) with 2 technical errata (Permanent home) |
Sept ?, 2013 | 0.11 | DSTU 1 Ballot version (Missing - hunting for a copy) |
Dec 4, 2012 | 0.06 | 2nd Draft for Comment (January 2013 Ballot) |
Sep 9, 2012 | 0.05 | 1st Draft for Comment (Sept 2012 Ballot) |
May 14, 2012 | 0.01 | Oldest Archive version available |
Note: Subsequent to Sept 2013, the FHIR version policy was changed.
FHIR Infrastructure Work Group | Maturity Level: N/A | Standards Status: Informative |
This page provides an index to the key commonly used documentation pages for FHIR.
Note: the N symbol indicates that the target of the link contains Normative content.
Maturity Level: 3 | Standards Status:Trial Use |
FHIR resources can be used to build documents that represent a composition: a set of coherent information that is a statement of healthcare information, including clinical observations and services. A document is an immutable set of resources with a fixed presentation that is authored and/or attested by humans, organizations and devices.
Documents built in this fashion may be exchanged between systems and persisted in document storage and management systems, including systems such as IHE XDS.
Applications claiming conformance to this framework claim to be conformant to "FHIR documents" (see Conformance).
FHIR documents may be 'clinical' (focused on patient healthcare information) but may also serve non-clinical purposes (e.g. FHIR Implementation guides, practice guidelines, patient handouts, etc.) HL7 will develop profiles in the future giving additional guidance on appropriate representation of clinical documents in general as well as specific types of clinical documents (e.g. Consolidated CDA).
Note that FHIR defines both this document format and a document reference resource. FHIR documents are for documents that are authored and assembled in FHIR, while the document reference resource is for general references to pre-existing documents.
All documents have the same structure: a Bundle
of resources of type "document"
that has a Composition resource as the first resource
in the bundle, followed by a series of other resources, referenced from the Composition
resource, that provide supporting evidence for the document. The bundle gathers all the content
of the document into a single XML or JSON document which may be signed and managed as required.
The resources include both human readable and computer processable portions. In addition, the bundle
may include CSS stylesheets,
Provenance statements and a signature.
The composition resource is the foundation of the clinical document. It:
Any resource referenced directly in the Composition SHALL be included in the bundle when the document is assembled. Specifically, this means the following resource references:
Other resources that these referenced resources refer to may also be included in the bundle if the document construction system chooses to do so. Including these additional resources will make the document bigger but will save applications from needing to retrieve the linked resources if they need them while processing the document. Thus, whether these linked resources should be included or not depends on the implementation environment.
The document bundle SHALL include only:
There are two key identifiers in the document:
The document has several dates in it:
Document Bundles may be signed using digital signatures following the rules laid out in the digital signatures page. The signature SHOULD be provided by a listed attester of the document and the signature SHOULD contain a KeyInfo element that contains a KeyName element whose value is a URI that matches the fullUri for the matching attester resource.
Once assembled into a bundle, the document is immutable - its content can never be changed, and the document id can never be reused. Note that the document may be represented in either XML or JSON and interconverted between these or have its character encoding changed, all the while remaining the same document. However, the directly referenced content within the document and the presentation of the document cannot change substantially (such that it changes the clinical meaning of the content). Any additional documents derived from the same composition SHALL have a different document id.
When the document is presented for human consumption, applications SHOULD present the collated narrative portions in order:
The presentation of the document is called the 'attested content' of the document. Additional
resources can be included in the bundle (e.g. resources referenced from the List that represent the section.content
SHOULD be in the bundle, and other additional resources they reference can be included), but these (and any narrative)
are not attested content. Specifically, the Composition.attester
attests to the presented form of the document.
The Composition resource narrative should summarize the important parts of the document header that are required to establish clinical context for the document (other than the subject, which is displayed in its own right). To actually build the combined narrative, simply append all the narrative <div> fragments together.
If the document is presented in a different order from that given above, it might not represent the original attested content. Implementation Guides may restrict document narrative and display behavior further.
The XML Tools reference implementation includes a XSLT transform that converts an XML document into browser-ready XHTML.
In addition to the basic style rules about Narratives, which must be followed, a document can reference or contain one or more stylesheets that contains additional styles that apply to the collated narrative. This is done by asserting stylesheet links on the feed:
<Bundle xmlns="http://hl7.org/fhir"> <!-- metadata and type --> <link> <relation value="stylesheet"/> <url value="[uri]"/> </link> </Bundle>
The url
can be an absolute reference to a CSS stylesheet or
a relative reference to a Binary resource that carries a
CSS stylesheet. Stylesheet references can only refer to
a CSS stylesheet - other forms of stylesheet are not acceptable.
Relative (internal) references SHOULD be used for stylesheets, because the viewer may be unable to resolve external content at the time of viewing, due to technical problems or local policy decisions.
Any stylesheet referenced or used SHALL NOT alter the presentation in such a way that it changes the clinical meaning of the content.
Unless otherwise agreed in local trading partner agreements, applications displaying the collated narrative SHOULD use the stylesheets specified by the document (see security note). Parties entering into a trading agreement to do otherwise should consider the implications this action will have on their long-term scope for document exchange very carefully. If the parties agree to use stylesheets that are not contained in the document, then it may be that they will never be able to share their documents safely in a more general context, such as a regional or national EHR or a global personal health record.
Document profiles are used to describe documents for a particular purpose. Document profiles may make rules about:
Applications should consider publishing Capability Statements that identify particular documents they support. Documents can
identify a profile that they conform to by placing a profile identifier in the Bundle.meta.profile
element - see Profile Tags for a discussion of the utility
of this.
The authors/constructors and processors of Clinical Documents, whether human or software, have obligations that they must satisfy.
A document constructor is an application that creates a document. An author is a human, organization or device that uses the constructor to create a document. Between them, the constructor and the author may create new content resources and/or assemble already existing content resources while performing their tasks. They also have the following responsibilities:
A document processor is an application and/or human user that receives documents and extracts data from them or makes decisions because of them. The documents may be received directly from a document constructor, accessed via a document management system or forwarded by a third party. The document processor is responsible for ensuring that received documents are processed and/or rendered in accordance to this specification. A document processor has the obligation to assure that the following rules are followed:
In addition to these obligations, document receivers SHOULD carefully track the source of documents for new documents that supersede existing documents, particularly when the documents represent compositions that have been retracted. When documents have been replaced, they SHOULD either withdraw data extracted from superseded documents or warn users when they view the document or data taken from it.
There are several different RESTful end-points used when working with documents. The use of the various end-points can best be described by considering the consequences of posting to them:
End-Point | Type of Content | Description |
[baseurl]/Bundle | Document Bundle | This works like a normal end-point for managing a type of resource, but it works with whole document bundles - i.e. a read operation returns a bundle, an update gets a bundle and a search returns a bundle of bundles. Note that if documents are POSTed using a create interaction the Bundle.id will change, but the Bundle.identifier will not. See Serving Bundles using the RESTful API for further comment |
[baseurl]/Composition | Composition Resource | The normal end-point for managing composition resources. This can be used while building a document or after breaking a document up into its constituent resources or when using compositions separately from documents |
[baseurl]/Binary | Document Bundle | Just store the entire document as a sequence of bytes and return exactly that sequence when requested. There is no way to find content in the /Binary end-point, so usually this would be associated with a Document Reference so that applications can find and process the document, though this is not required |
[baseurl] (e.g. a transaction) | Document Bundle | Ignore the fact that the bundle is a document and process all of the resources that it contains as individual resources. Clients SHOULD not expect that a server that receives a document submitted using this method will be able to reassemble the document exactly. (Even if the server can reassemble the document (see below), the result cannot be expected to be in the same order, etc. Thus a document signature will very likely be invalid.). See Accepting other Bundle types for further details |
Note: While these end-points are defined for use with document-related resources and document bundles, it is not necessary to use them. Documents may be transferred between systems using any method desired. In addition, servers and/or specifications may define additional operations for handling documents beyond the options described above.
A client can ask a server to generate a fully bundled document from a composition resource. For details, see Generate Document Operation.
Maturity Level: N/A | Standards Status:Informative |
See MedicationRequest examples for examples using Dosage.
Maturity Level: N/A | Standards Status:Informative |
This page provides mappings for Dosage (see Mappings to Other Standards for further information & status).