FHIR CI-Build

This is the Continuous Integration Build of FHIR (will be incorrect/inconsistent at times).
See the Directory of published versions icon

2.1.28.0 Datatypes

Modeling and Methodology icon Work GroupMaturity Level: NormativeStandards Status: Partially Normative

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

The FHIR specification defines a set of datatypes that are used for the resource elements. There are five categories of datatypes:

  1. The base abstract types that provide the foundation for all types
  2. Simple / primitive types, which are single elements with a primitive value (below)
  3. General-purpose complex types, which are re-usable clusters of elements (below)
  4. MetaDatatypes: A set of types for use with metadata resources
  5. Special purpose datatypes - defined elsewhere in the specification for specific usages: Reference, Meta, Narrative, Extension, xhtml, ElementDefinition and Dosage.

This page describes the general-purpose datatypes (categories 1 and 2).

Datatypes Summary.

Legend: see Standards Status Colors

A limited set of these datatypes may appear in extensions. All datatypes (including primitives) may have extensions, but only the following datatypes may include Modifier Extensions:

PrimitiveTypeinstantActual value attribute of the datatypevalue : xs:dateTime 0..1timeActual value attribute of the datatypevalue : xs:time 0..1dateActual value attribute of the datatypevalue : xs:gYear|xs:gYearMonth|xs:date 0..1dateTimeActual value attribute of the datatypevalue : xs:gYear|xs:gYearMonth|xs:date|xs:dateTime 0..1decimalActual value attribute of the datatypevalue : xs:decimal|xs:double 0..1booleanActual value attribute of the datatypevalue : xs:boolean 0..1integerActual value attribute of the datatypevalue : xs:int 0..1stringActual value attribute of the datatypevalue : xs:string 0..1uriActual value attribute of the datatypevalue : xs:anyURI 0..1base64BinaryActual value attribute of the datatypevalue : xs:base64Binary 0..1codeidoidunsignedIntpositiveIntmarkdownurlcanonicaluuidinteger64Actual value attribute of the datatypevalue : xs:long 0..1

The following table describes the primitive types that are used in this specification. Primitive types are those that specialize PrimitiveType, with a value, and no additional elements as children (though, like all types, they have id and extensions). See also the Examples.

Primitive Types
FHIR Name Value Domain XML Representation JSON representation
base64Binary A stream of bytes, base64 encoded (RFC 4648 icon). base64Binary content does not include any whitespace or line feeds, but reading applications should ignore whitespace characters (per RFC 4648 icon) xs:base64Binary A JSON string - base64 content
Regex: (?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)? XML Definition JSON Definition
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 way for this at this time
boolean true | false xs:boolean, except that 0 and 1 are not valid values JSON boolean (true or false)
Regex: true|false XML Definition JSON Definition
canonical A URI that refers to a resource by its 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. Unlike other URIs, canonical URLs are never relative - they are either absolute URIs, or fragment identifiers xs:anyURI A JSON string - a canonical URL
Regex: \S* XML Definition JSON Definition
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]+)*
This datatype can be bound to a ValueSet
XML Definition JSON Definition
date A date, or partial date (e.g. just year or year + month) as used in human communication. The format is a subset of [ISO8601] icon: YYYY, YYYY-MM, or YYYY-MM-DD, e.g. 2018, 1973-06, or 1905-08-23. There SHALL be no timezone offset. 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])
)?)?
XML Definition JSON Definition
dateTime A date, date-time or partial date (e.g. just year or year + month) as used in human communication. The format is a subset of [ISO8601] icon: 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 timezone offset SHALL be populated. Actual timezone codes can be sent using the Timezone Code extension, if desired. Seconds must be provided due to schema type constraints but may be zero-filled and may be ignored at receiver discretion. Milliseconds are optionally allowed. 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]{1,9})?)?)?(Z|(\+|-)((0[0-9]|1[0-3]):[0-
5][0-9]|14:00)?)?)?
XML Definition JSON Definition
decimal Rational numbers that have a decimal representation. Decimals in FHIR cannot have more than 18 digits and a decimal point. 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,17})(\.[0-9]{1,17})?([eE][+-]?[0-9]{1,9}})? XML Definition JSON Definition
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: [A-Za-z0-9\-\.]{1,64} XML Definition JSON Definition
instant An instant in time in a format that is a subset of [ISO8601] icon: 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 timezone offset. Actual timezone codes can be sent using the [[[http://hl7.org/fhir/StructureDefinition/timezone extension]]], if desired. 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]{1,9})?(Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]
|14:00))
XML Definition JSON Definition
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]* XML Definition JSON Definition
integer64 A signed integer in the range -9,223,372,036,854,775,808 to +9,223,372,036,854,775,807 (64-bit).
This type is defined to allow for record/time counters that can get very large
xs:long, except that leading 0 digits are not allowed JSON String (due to issues with precision in floating point libraries)
Regex: [0]|[-+]?[1-9][0-9]* XML Definition JSON Definition
markdown A FHIR string (see below) 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]+$ (can't put size limit in the regex - too large) XML Definition JSON Definition
oid An OID represented as a URI (RFC 3001 icon); e.g. urn:oid:1.2.3.4.5 xs:anyURI JSON string - uri
Regex: urn:oid:[0-2](\.(0|[1-9][0-9]*))+ XML Definition JSON Definition
string A sequence of Unicode characters xs:string JSON String
Note that strings SHALL NOT exceed 1,048,576 (1024*1024) characters in size. Because UTF-8 characters can be expressed with more than one byte, the string size may be more than 1MB. Strings SHOULD not contain Unicode character points below 32, except for u0009 (horizontal tab), u000D (carriage return) and u000A (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 datatype can be bound to a ValueSet
Regex: ^[\s\S]+$ (see notes below) XML Definition JSON Definition
positiveInt Any positive integer in the range 1..2,147,483,647 xs:positiveInteger JSON number
Regex: [1-9][0-9]* XML Definition JSON Definition
time A time during the day, in the format hh:mm:ss (a subset of [ISO8601] icon). 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 timezone offset 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]{1,9})? XML Definition JSON Definition
unsignedInt Any non-negative integer in the range 0..2,147,483,647 xs:nonNegativeInteger JSON number
Regex: [0]|([1-9][0-9]*) XML Definition JSON Definition
uri A Uniform Resource Identifier Reference (RFC 3986 icon). 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) XML Definition JSON Definition
URIs can be absolute or relative, and may have an optional fragment identifier
This datatype can be bound to a ValueSet
url A Uniform Resource Locator (RFC 1738 icon). 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
Regex: \S* XML Definition JSON Definition
uuid A UUID (aka GUID) represented as a URI (RFC 4122 icon); e.g. urn:uuid:c757873d-ec9a-4326-a141-556f43239520 xs:anyURI JSON string - uri
Regex: urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12} XML Definition JSON Definition

Notes:

  • For all the types, the XML, JSON and Turtle representations of the primitive values are the same except for different escaping in XML and JSON
  • For string content, parsers and serializers MAY retain, escape or strip unescaped non-supported UNICODE characters. If the characters are retained, a subsequent application-layer process can then determine appropriate handling based on context.
  • For decimal values, the XML special values 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 icon
  • The precision of the decimal value has significance:
    • e.g. 0.010 is regarded as different to 0.01, and the original precision should be preserved
    • Implementations SHALL handle decimal values in ways that preserve and respect the precision of the value as represented for presentation purposes.
    • Implementations are not required to perform calculations with these numbers differently, though they may choose to do so (i.e. preserve significance).
    • See implementation comments for XML, JSON and RDF.
    • In object code, implementations that might meet this constraint are GMP implementations or equivalents to Java BigDecimal that implement arbitrary precision, or a combination of a (64 bit) floating point value with a precision field.
    • Note that large and/or highly precise values are extremely rare in medicine. One element where highly precise decimals may be encountered is the Location coordinates. Irrespective of this, the limits documented in XML Schema apply.
  • Boolean values can also be represented using coded values (such as HL7 V2 Table 0136). See Observation for one such use.
  • Issues with the specified regexes:
    • The regexes are provided to assist with tooling, but are informative, not normative. There are several issues with the regexes.
    • The string regex has problems with Unicode - specifically, it might or might not allow Unicode whitespace to some degree depending on Unicode support in the regex engine being used. The regexes [\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 icon for details). The string regex also applies to markdown as well. The regex does not enforce the length limit
    • The Unicode issues also apply to the regex for code.
    • The regexes should be qualified with start of string and end of string anchors based on the regex implementation used (e.g. caret '^' and dollar-sign '$' for JavaScript, POSIX, XML and XPath; '\A' and '\Z' for .NET, Java, Python and others; please verify these definitions with the regex implementation used).
    • The regexes may allow a broader set of values than are actually valid (e.g. leap years) so additional validation is always needed.
  • Leap second are allowed in the datetime, instant and time types. Note, though, that many systems and libraries do not support leap seconds. Applications reading times SHOULD accept and handle leap seconds gracefully, and applications producing them MAY choose to avoid encoding leap seconds.
  • About the id datatype:
    • Ids are case sensitive. UUIDs SHALL be sent using lowercase letters.
    • The ID type includes identifiers consistent with ISO 18232 icon, but also includes other identifier formats as well, and is not case insensitive like ISO 18232.
    • In a typical FHIR URL, like http://example.com/fhir/Patient/1234, the last part "1234" (highlighted in red) is the part that is an id datatype.
    • A full UUID is a uri, not an id. UUIDs in URIs SHALL also be represented in lowercase (urn:uuid:59bf0ef4-e89c-4628-9b51-12ae3fdbe22b).
  • About the uri, url and canonical datatypes:
    • They all contain URIs, but differ in how applications resolve the reference.
    • Although the url and canonical are specializations of uri, they are never substituted for each other.
    • They are all case sensitive for comparison purposes. Applications SHOULD not create URIs that only differ by case.
    • A general URI may be either a URL or a canonical URL or some other kind of URI.
  • About the markdown datatype:
    • Markdown is a string, and subject to the same rules (e.g. length limit, valid characters)
    • This specification requires and uses the GFM (Github Flavored Markdown) icon extensions on CommonMark icon format, with the exception of support for inline HTML which is not supported.
    • Processors SHALL treat embedded XML tags as string content, not as tags. This may be done by pre-processing and escaping any ">" characters preceding character content (">" becomes "\>") before processing the content or by using a markdown processor-specific flag that accomplishes the same effect. This means that HTML content cannot be embedded in markdown to influence rendering.
    • Systems are not required to have markdown support, so the content of a string should be readable without markdown processing, per markdown philosophy.
    • Converting an element that has the type string to markdown in a later version of this FHIR specification is considered a non-breaking change for elements with a single type. It is a breaking change for multi-type/choice elements because the type name is reflected in the element name. (Adding markdown as an additional choice to a multi-type element is not a breaking change). The impact of a lack of escaping on existing string data on safe rendering should be considered in evaluating changes from string to markdown - see next bullet.
    • WARNING: Because markdown renderers will interpret certain characters as formatting characters and strip them from the display, it is essential that systems transmitting plain string data in a markdown field take steps to appropriately escape the string to avoid loss of information when rendering for human display.

Implementation Note: A simple way to convert plain text to be safe as markdown is to prefix any of the characters *, &, #, [, <, >, and ` with a backslash (\). When presenting markdown as plain text, implementers may wish to reverse this transform.

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://hl7.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 datatype 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 datatypes 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 Datatypes

DataTypeQuantityThe value of the measured amount. The value includes an implicit precision in the presentation of the valuevalue : decimal [0..1]How the value should be understood and represented - whether the actual value is greater or less than the stated value due to measurement issues; e.g. if the comparator is "<" , then the real value is < stated value (this element modifies the meaning of other elements)comparator : code [0..1] « How the Quantity should be understood and represented. (Strength=Required)QuantityComparator! »A human-readable form of the unitunit : string [0..1]The identification of the system that provides the coded form of the unitsystem : uri [0..1] « This element has or is affected by some invariantsC »A computer processable form of the unit in some unit representation systemcode : code [0..1] « This element has or is affected by some invariantsC »AgeDistanceDurationCountMoneyQuantitySimpleQuantityAttachmentIdentifies the type of the data in the attachment and allows a method to be chosen to interpret or render the data. Includes mime type parameters such as charset where appropriatecontentType : code [0..1] « The mime type of an attachment. Any valid mime type is allowed. (Strength=Required)MimeTypes! » « This element has or is affected by some invariantsC »The human language of the content. The value can be any valid value according to BCP 47language : code [0..1] « IETF language tag for a human language. (Strength=Required)AllLanguages! »The actual data of the attachment - a sequence of bytes, base64 encodeddata : base64Binary [0..1] « This element has or is affected by some invariantsC »A location where the data can be accessedurl : url [0..1]The number of bytes of data that make up this attachment (before base64 encoding, if that is done)size : integer64 [0..1]The calculated hash of the data using SHA-1. Represented using base64hash : base64Binary [0..1]A label or set of text to display in place of the datatitle : string [0..1]The date that the attachment was first createdcreation : dateTime [0..1]Height of the image in pixels (photo/video)height : positiveInt [0..1]Width of the image in pixels (photo/video)width : positiveInt [0..1]The number of frames in a photo. This is used with a multi-page fax, or an imaging acquisition context that takes multiple slices in a single image, or an animated gif. If there is more than one frame, this SHALL have a value in order to alert interface software that a multi-frame capable rendering widget is requiredframes : positiveInt [0..1]The duration of the recording in seconds - for audio and videoduration : decimal [0..1]The number of pages when printedpages : positiveInt [0..1]RangeThe low limit. The boundary is inclusivelow : Quantity(SimpleQuantity) [0..1] « This element has or is affected by some invariantsC »The high limit. The boundary is inclusivehigh : Quantity(SimpleQuantity) [0..1] « This element has or is affected by some invariantsC »PeriodThe start of the period. The boundary is inclusivestart : dateTime [0..1] « This element has or is affected by some invariantsC »The end of the period. If the end of the period is missing, it means no end was known or planned at the time the instance was created. The start may be in the past, and the end date in the future, which means that period is expected/planned to end at that timeend : dateTime [0..1] « This element has or is affected by some invariantsC »RatioThe value of the numeratornumerator : Quantity [0..1] « This element has or is affected by some invariantsC »The value of the denominatordenominator : Quantity(SimpleQuantity) [0..1] « This element has or is affected by some invariantsC »RatioRangeThe value of the low limit numeratorlowNumerator : Quantity(SimpleQuantity) [0..1] « This element has or is affected by some invariantsC »The value of the high limit numeratorhighNumerator : Quantity(SimpleQuantity) [0..1] « This element has or is affected by some invariantsC »The value of the denominatordenominator : Quantity(SimpleQuantity) [0..1] « This element has or is affected by some invariantsC »CodeableConceptA reference to a code defined by a terminology systemcoding : Coding [0..*]A human language representation of the concept as seen/selected/uttered by the user who entered the data and/or which represents the intended meaning of the usertext : string [0..1]CodingThe identification of the code system that defines the meaning of the symbol in the codesystem : uri [0..1]The version of the code system which was used when choosing this code. Note that a well-maintained code system does not need the version reported, because the meaning of codes is consistent across versions. However this cannot consistently be assured, and when the meaning is not guaranteed to be consistent, the version SHOULD be exchangedversion : string [0..1]A symbol in syntax defined by the system. The symbol may be a predefined code or an expression in a syntax defined by the coding system (e.g. post-coordination)code : code [0..1] « This element has or is affected by some invariantsC »A representation of the meaning of the code in the system, following the rules of the systemdisplay : string [0..1] « This element has or is affected by some invariantsC »Indicates that this coding was chosen by a user directly - e.g. off a pick list of available items (codes or displays)userSelected : boolean [0..1]AnnotationThe individual responsible for making the annotationauthor[x] : DataType [0..1] « Reference(Practitioner| PractitionerRole|Patient|RelatedPerson|Organization)|string »Indicates when this particular annotation was madetime : dateTime [0..1]The text of the annotation in markdown formattext : markdown [1..1]MoneyNumerical value (with implicit precision)value : decimal [0..1]ISO 4217 Currency Codecurrency : code [0..1] « A code indicating the currency, taken from ISO 4217. (Strength=Required)Currencies! »
DataTypeIdentifierThe purpose of this identifier (this element modifies the meaning of other elements)use : code [0..1] « Identifies the purpose for this identifier, if known . (Strength=Required)IdentifierUse! »A coded type for the identifier that can be used to determine which identifier to use for a specific purposetype : CodeableConcept [0..1] « A coded type for an identifier that can be used to determine which identifier to use for a specific purpose. (Strength=Extensible)IdentifierTypeCodes+ »Establishes the namespace for the value - that is, an absolute URL that describes a set values that are uniquesystem : uri [0..1]The portion of the identifier typically relevant to the user and which is unique within the context of the systemvalue : string [0..1] « This element has or is affected by some invariantsC »Time period during which identifier is/was valid for useperiod : Period [0..1]Organization that issued/manages the identifierassigner : Reference [0..1] « Organization »HumanNameIdentifies the purpose for this name (this element modifies the meaning of other elements)use : code [0..1] « The use of a human name. (Strength=Required)NameUse! »Specifies the entire name as it should be displayed e.g. on an application UI. This may be provided instead of or as well as the specific partstext : string [0..1]The part of a name that links to the genealogy. In some cultures (e.g. Eritrea) the family name of a son is the first name of his fatherfamily : string [0..1]Given namegiven : string [0..*]Part of the name that is acquired as a title due to academic, legal, employment or nobility status, etc. and that appears at the start of the nameprefix : string [0..*]Part of the name that is acquired as a title due to academic, legal, employment or nobility status, etc. and that appears at the end of the namesuffix : string [0..*]Indicates the period of time when this name was valid for the named personperiod : Period [0..1]AddressThe purpose of this address (this element modifies the meaning of other elements)use : code [0..1] « The use of an address. (Strength=Required)AddressUse! »Distinguishes between physical addresses (those you can visit) and mailing addresses (e.g. PO Boxes and care-of addresses). Most addresses are bothtype : code [0..1] « The type of an address (physical / postal). (Strength=Required)AddressType! »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 partstext : string [0..1]This component contains the house number, apartment number, street name, street direction, P.O. Box number, delivery hints, and similar address informationline : string [0..*]The name of the city, town, suburb, village or other community or delivery centercity : string [0..1]The name of the administrative area (county)district : string [0..1]Sub-unit of a country with limited sovereignty in a federally organized country. A code may be used if codes are in common use (e.g. US 2 letter state codes)state : string [0..1]A postal code designating a region defined by the postal servicepostalCode : string [0..1]Country - a nation as commonly understood or generally acceptedcountry : string [0..1]Time period when address was/is in useperiod : Period [0..1]ContactPointTelecommunications form for contact point - what communications system is required to make use of the contactsystem : code [0..1] « Telecommunications form for contact point. (Strength=Required)ContactPointSystem! » « This element has or is affected by some invariantsC »The actual contact point details, in a form that is meaningful to the designated communication system (i.e. phone number or email address)value : string [0..1] « This element has or is affected by some invariantsC »Identifies the purpose for the contact point (this element modifies the meaning of other elements)use : code [0..1] « Use of contact point. (Strength=Required)ContactPointUse! »Specifies a preferred order in which to use a set of contacts. ContactPoints with lower rank values are more preferred than those with higher rank valuesrank : positiveInt [0..1]Time period when the contact point was/is in useperiod : Period [0..1]TimingIdentifies specific times when the event occursevent : dateTime [0..*]A code for the timing schedule (or just text in code.text). Some codes such as BID are ubiquitous, but many institutions define their own additional codes. If a code is provided, the code is understood to be a complete statement of whatever is specified in the structured timing data, and either the code or the data may be used to interpret the Timing, with the exception that .repeat.bounds still applies over the code (and is not contained in the code)code : CodeableConcept [0..1] « Code for a known / defined timing pattern. (Strength=Preferred)TimingAbbreviation? »RepeatEither a duration for the length of the timing schedule, a range of possible length, or outer bounds for start and/or end limits of the timing schedulebounds[x] : DataType [0..1] « Duration|Range|Period »A total count of the desired number of repetitions across the duration of the entire timing specification. If countMax is present, this element indicates the lower bound of the allowed range of count valuescount : positiveInt [0..1] « This element has or is affected by some invariantsC »If present, indicates that the count is a range - so to perform the action between [count] and [countMax] timescountMax : positiveInt [0..1] « This element has or is affected by some invariantsC »How long this thing happens for when it happens. If durationMax is present, this element indicates the lower bound of the allowed range of the durationduration : decimal [0..1] « This element has or is affected by some invariantsC »If present, indicates that the duration is a range - so to perform the action between [duration] and [durationMax] time lengthdurationMax : decimal [0..1] « This element has or is affected by some invariantsC »The units of time for the duration, in UCUM units Normal practice is to use the 'mo' code as a calendar month when calculating the next occurrencedurationUnit : code [0..1] « A unit of time (units from UCUM). (Strength=Required)UnitsOfTime! » « This element has or is affected by some invariantsC »The number of times to repeat the action within the specified period. If frequencyMax is present, this element indicates the lower bound of the allowed range of the frequencyfrequency : positiveInt [0..1]If present, indicates that the frequency is a range - so to repeat between [frequency] and [frequencyMax] times within the period or period rangefrequencyMax : positiveInt [0..1]Indicates the duration of time over which repetitions are to occur; e.g. to express "3 times per day", 3 would be the frequency and "1 day" would be the period. If periodMax is present, this element indicates the lower bound of the allowed range of the period lengthperiod : decimal [0..1] « This element has or is affected by some invariantsC »If present, indicates that the period is a range from [period] to [periodMax], allowing expressing concepts such as "do this once every 3-5 daysperiodMax : decimal [0..1] « This element has or is affected by some invariantsC »The units of time for the period in UCUM units Normal practice is to use the 'mo' code as a calendar month when calculating the next occurrenceperiodUnit : code [0..1] « A unit of time (units from UCUM). (Strength=Required)UnitsOfTime! » « This element has or is affected by some invariantsC »If one or more days of week is provided, then the action happens only on the specified day(s)dayOfWeek : code [0..*] « (Strength=Required)DaysOfWeek! »Specified time of day for action to take placetimeOfDay : time [0..*] « This element has or is affected by some invariantsC »An approximate time period during the day, potentially linked to an event of daily living that indicates when the action should occurwhen : code [0..*] « Real-world event relating to the schedule. (Strength=Required)EventTiming! » « This element has or is affected by some invariantsC »The number of minutes from the event. If the event code does not indicate whether the minutes is before or after the event, then the offset is assumed to be after the eventoffset : unsignedInt [0..1] « This element has or is affected by some invariantsC »SignatureAn indication of the reason that the entity signed this document. This may be explicitly included as part of the signature information and can be used when determining accountability for various actions concerning the documenttype : Coding [0..*] « An indication of the reason that an entity signed the object. (Strength=Preferred)SignatureTypeCodes? »When the digital signature was signedwhen : instant [0..1]A reference to an application-usable description of the identity that signed (e.g. the signature used their private key)who : Reference [0..1] « Practitioner|PractitionerRole|RelatedPerson| Patient|Device|Organization »A reference to an application-usable description of the identity that is represented by the signatureonBehalfOf : Reference [0..1] « Practitioner|PractitionerRole| RelatedPerson|Patient|Device|Organization »A mime type that indicates the technical format of the target resources signed by the signaturetargetFormat : code [0..1] « The mime type of an attachment. Any valid mime type is allowed. (Strength=Required)MimeTypes! »A mime type that indicates the technical format of the signature. Important mime types are application/signature+xml for X ML DigSig, application/jose for JWS, and image/* for a graphical image of a signature, etcsigFormat : code [0..1] « The mime type of an attachment. Any valid mime type is allowed. (Strength=Required)MimeTypes! »The base64 encoding of the Signature content. When signature is not recorded electronically this element would be emptydata : base64Binary [0..1]SampledDataThe base quantity that a measured value of zero represents. In addition, this provides the units of the entire measurement seriesorigin : Quantity(SimpleQuantity) [1..1]Amount of intervalUnits between samples, e.g. milliseconds for time-based samplinginterval : decimal [0..1] « This element has or is affected by some invariantsC »The measurement unit in which the sample interval is expressedintervalUnit : code [1..1] « Units of measure allowed for an element. (Strength=Required)UCUMCodes! »A correction factor that is applied to the sampled data points before they are added to the originfactor : decimal [0..1]The lower limit of detection of the measured points. This is needed if any of the data points have the value "L" (lower than detection limit)lowerLimit : decimal [0..1]The upper limit of detection of the measured points. This is needed if any of the data points have the value "U" (higher than detection limit)upperLimit : decimal [0..1]The number of sample points at each time point. If this value is greater than one, then the dimensions will be interlaced - all the sample points for a point in time will be recorded at oncedimensions : positiveInt [1..1]Reference to ConceptMap that defines the codes used in the datacodeMap : canonical [0..1] « ConceptMap »A series of data points which are decimal values separated by a single space (character u20). The units in which the offsets are expressed are found in intervalUnit. The absolute point at which the measurements begin SHALL be conveyed outside the scope of this datatype, e.g. Observation.effectiveDateTime for a timing offsetoffsets : string [0..1] « This element has or is affected by some invariantsC »A series of data points which are decimal values or codes separated by a single space (character u20). The special codes "E" (error), "L" (below detection limit) and "U" (above detection limit) are also defined for used in place of decimal valuesdata : string [0..1]BackboneTypeMay be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and managable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself) (this element modifies the meaning of other elements)modifierExtension : Extension [0..*]A set of rules that describe when the event is scheduledrepeat[0..1]
FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Normative

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 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.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. AttachmentNElementContent in a format defined elsewhere
+ Rule: If the Attachment has data, it SHALL have a contentType

Elements defined in Ancestors: id, extension
... contentTypeΣC0..1codeMime type of the content, with charset etc.
Binding: Mime Types (Required)
... languageΣ0..1codeHuman language of the content (BCP-47)
Binding: All Languages (Required)
Additional BindingsPurpose
Common LanguagesStarter Set

... dataC0..1base64BinaryData inline, base64ed
... sizeΣ0..1integer64Number of bytes of content (if url provided)
... hashΣ0..1base64BinaryHash of the data (sha-1, base64ed)
... titleΣT0..1stringLabel to display in place of the data
... creationΣ0..1dateTimeDate attachment was first created
... heightTU0..1positiveIntHeight of the image in pixels (photo/video)
... widthTU0..1positiveIntWidth of the image in pixels (photo/video)
... framesTU0..1positiveIntNumber of frames if > 1 (photo)
... durationTU0..1decimalLength in seconds (audio / video)
... pagesTU0..1positiveIntNumber of printed pages

doco Documentation for this format icon

Definition: XML | JSON

UML Diagram (Legend)

AttachmentIdentifies the type of the data in the attachment and allows a method to be chosen to interpret or render the data. Includes mime type parameters such as charset where appropriatecontentType : code [0..1] « The mime type of an attachment. Any valid mime type is allowed. (Strength=Required)MimeTypes! » « This element has or is affected by some invariantsC »The human language of the content. The value can be any valid value according to BCP 47language : code [0..1] « IETF language tag for a human language. (Strength=Required)AllLanguages! »The actual data of the attachment - a sequence of bytes, base64 encodeddata : base64Binary [0..1] « This element has or is affected by some invariantsC »A location where the data can be accessedurl : url [0..1]The number of bytes of data that make up this attachment (before base64 encoding, if that is done)size : integer64 [0..1]The calculated hash of the data using SHA-1. Represented using base64hash : base64Binary [0..1]A label or set of text to display in place of the datatitle : string [0..1]The date that the attachment was first createdcreation : dateTime [0..1]Height of the image in pixels (photo/video)height : positiveInt [0..1]Width of the image in pixels (photo/video)width : positiveInt [0..1]The number of frames in a photo. This is used with a multi-page fax, or an imaging acquisition context that takes multiple slices in a single image, or an animated gif. If there is more than one frame, this SHALL have a value in order to alert interface software that a multi-frame capable rendering widget is requiredframes : positiveInt [0..1]The duration of the recording in seconds - for audio and videoduration : decimal [0..1]The number of pages when printedpages : positiveInt [0..1]DataType

XML Template

<Attachment xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <contentType value="[code]"/><!-- I 0..1 Mime type of the content, with charset etc. -->
 <language value="[code]"/><!-- 0..1 Human language of the content (BCP-47) -->
 <data value="[base64Binary]"/><!-- I 0..1 Data inline, base64ed -->
 <url value="[url]"/><!-- 0..1 Uri where the data can be found -->
 <size value="[integer64]"/><!-- 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 -->
 <creation value="[dateTime]"/><!-- 0..1 Date attachment was first created -->
 <height value="[positiveInt]"/><!-- 0..1 Height of the image in pixels (photo/video) -->
 <width value="[positiveInt]"/><!-- 0..1 Width of the image in pixels (photo/video) -->
 <frames value="[positiveInt]"/><!-- 0..1 Number of frames if > 1 (photo) -->
 <duration value="[decimal]"/><!-- 0..1 Length in seconds (audio / video) -->
 <pages value="[positiveInt]"/><!-- 0..1 Number of printed pages -->
</Attachment>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:contentType [ code ] ; # 0..1 I Mime type of the content, with charset etc.
  fhir:language [ code ] ; # 0..1 Human language of the content (BCP-47)
  fhir:data [ base64Binary ] ; # 0..1 I Data inline, base64ed
  fhir:url [ url ] ; # 0..1 Uri where the data can be found
  fhir:size [ integer64 ] ; # 0..1 Number of bytes of content (if url provided)
  fhir:hash [ base64Binary ] ; # 0..1 Hash of the data (sha-1, base64ed)
  fhir:title [ string ] ; # 0..1 Label to display in place of the data
  fhir:creation [ dateTime ] ; # 0..1 Date attachment was first created
  fhir:height [ positiveInt ] ; # 0..1 Height of the image in pixels (photo/video)
  fhir:width [ positiveInt ] ; # 0..1 Width of the image in pixels (photo/video)
  fhir:frames [ positiveInt ] ; # 0..1 Number of frames if > 1 (photo)
  fhir:duration [ decimal ] ; # 0..1 Length in seconds (audio / video)
  fhir:pages [ positiveInt ] ; # 0..1 Number of printed pages
]

Changes since Release 3

Changes from both R4 and R4B

Attachment
Attachment.language
Attachment.size
  • Type changed from unsignedInt to integer64
Attachment.height
  • Added Element
Attachment.width
  • Added Element
Attachment.frames
  • Added Element
Attachment.duration
  • Added Element
Attachment.pages
  • Added Element

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. AttachmentNElementContent in a format defined elsewhere
+ Rule: If the Attachment has data, it SHALL have a contentType

Elements defined in Ancestors: id, extension
... contentTypeΣC0..1codeMime type of the content, with charset etc.
Binding: Mime Types (Required)
... languageΣ0..1codeHuman language of the content (BCP-47)
Binding: All Languages (Required)
Additional BindingsPurpose
Common LanguagesStarter Set

... dataC0..1base64BinaryData inline, base64ed
... sizeΣ0..1integer64Number of bytes of content (if url provided)
... hashΣ0..1base64BinaryHash of the data (sha-1, base64ed)
... titleΣT0..1stringLabel to display in place of the data
... creationΣ0..1dateTimeDate attachment was first created
... heightTU0..1positiveIntHeight of the image in pixels (photo/video)
... widthTU0..1positiveIntWidth of the image in pixels (photo/video)
... framesTU0..1positiveIntNumber of frames if > 1 (photo)
... durationTU0..1decimalLength in seconds (audio / video)
... pagesTU0..1positiveIntNumber of printed pages

doco Documentation for this format icon

UML Diagram (Legend)

AttachmentIdentifies the type of the data in the attachment and allows a method to be chosen to interpret or render the data. Includes mime type parameters such as charset where appropriatecontentType : code [0..1] « The mime type of an attachment. Any valid mime type is allowed. (Strength=Required)MimeTypes! » « This element has or is affected by some invariantsC »The human language of the content. The value can be any valid value according to BCP 47language : code [0..1] « IETF language tag for a human language. (Strength=Required)AllLanguages! »The actual data of the attachment - a sequence of bytes, base64 encodeddata : base64Binary [0..1] « This element has or is affected by some invariantsC »A location where the data can be accessedurl : url [0..1]The number of bytes of data that make up this attachment (before base64 encoding, if that is done)size : integer64 [0..1]The calculated hash of the data using SHA-1. Represented using base64hash : base64Binary [0..1]A label or set of text to display in place of the datatitle : string [0..1]The date that the attachment was first createdcreation : dateTime [0..1]Height of the image in pixels (photo/video)height : positiveInt [0..1]Width of the image in pixels (photo/video)width : positiveInt [0..1]The number of frames in a photo. This is used with a multi-page fax, or an imaging acquisition context that takes multiple slices in a single image, or an animated gif. If there is more than one frame, this SHALL have a value in order to alert interface software that a multi-frame capable rendering widget is requiredframes : positiveInt [0..1]The duration of the recording in seconds - for audio and videoduration : decimal [0..1]The number of pages when printedpages : positiveInt [0..1]DataType

XML Template

<Attachment xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <contentType value="[code]"/><!-- I 0..1 Mime type of the content, with charset etc. -->
 <language value="[code]"/><!-- 0..1 Human language of the content (BCP-47) -->
 <data value="[base64Binary]"/><!-- I 0..1 Data inline, base64ed -->
 <url value="[url]"/><!-- 0..1 Uri where the data can be found -->
 <size value="[integer64]"/><!-- 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 -->
 <creation value="[dateTime]"/><!-- 0..1 Date attachment was first created -->
 <height value="[positiveInt]"/><!-- 0..1 Height of the image in pixels (photo/video) -->
 <width value="[positiveInt]"/><!-- 0..1 Width of the image in pixels (photo/video) -->
 <frames value="[positiveInt]"/><!-- 0..1 Number of frames if > 1 (photo) -->
 <duration value="[decimal]"/><!-- 0..1 Length in seconds (audio / video) -->
 <pages value="[positiveInt]"/><!-- 0..1 Number of printed pages -->
</Attachment>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:contentType [ code ] ; # 0..1 I Mime type of the content, with charset etc.
  fhir:language [ code ] ; # 0..1 Human language of the content (BCP-47)
  fhir:data [ base64Binary ] ; # 0..1 I Data inline, base64ed
  fhir:url [ url ] ; # 0..1 Uri where the data can be found
  fhir:size [ integer64 ] ; # 0..1 Number of bytes of content (if url provided)
  fhir:hash [ base64Binary ] ; # 0..1 Hash of the data (sha-1, base64ed)
  fhir:title [ string ] ; # 0..1 Label to display in place of the data
  fhir:creation [ dateTime ] ; # 0..1 Date attachment was first created
  fhir:height [ positiveInt ] ; # 0..1 Height of the image in pixels (photo/video)
  fhir:width [ positiveInt ] ; # 0..1 Width of the image in pixels (photo/video)
  fhir:frames [ positiveInt ] ; # 0..1 Number of frames if > 1 (photo)
  fhir:duration [ decimal ] ; # 0..1 Length in seconds (audio / video)
  fhir:pages [ positiveInt ] ; # 0..1 Number of printed pages
]

Changes since Release 3

Changes from both R4 and R4B

Attachment
Attachment.language
Attachment.size
  • Type changed from unsignedInt to integer64
Attachment.height
  • Added Element
Attachment.width
  • Added Element
Attachment.frames
  • Added Element
Attachment.duration
  • Added Element
Attachment.pages
  • Added Element

See the Full Difference for further information

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

Constraints

idLevelLocationDescriptionExpression
img att-1Rule (base)If the Attachment has data, it SHALL have a contentTypedata.empty() or contentType.exists()

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.

Terminology Bindings

PathValueSetTypeDocumentation
Attachment.contentType MimeTypes (a valid code from urn:ietf:bcp:13)Required

This value set includes all possible codes from BCP-13 (see http://tools.ietf.org/html/bcp13)

Attachment.language AllLanguages (a valid code from Tags for the Identification of Languages icon)Required

This value set includes all possible codes from BCP-47 (see http://tools.ietf.org/html/bcp47)

  Common Languages starter

Attachment is used in the following places: RelatedArtifact, AdministrableProductDefinition, BiologicallyDerivedProduct, BodyStructure, Citation, Claim, ClaimResponse, Communication, CommunicationRequest, Consent, Contract, Device, DeviceDefinition, DiagnosticReport, DocumentReference, ExplanationOfBenefit, HealthcareService, Library, ManufacturedItemDefinition, MedicationKnowledge, MedicinalProductDefinition, MolecularSequence, NutritionProduct, Observation, PackagedProductDefinition, Patient, Person, Practitioner, Questionnaire, QuestionnaireResponse, RelatedPerson, SubstanceDefinition, SubstanceNucleicAcid, SubstancePolymer and SubstanceProtein

FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Normative

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 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 datatype can be bound to a ValueSet.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. CodingΣNElementA reference to a code defined by a terminology system
+ Warning: A Coding SHOULD NOT have a display unless a code is also present. Computation on Coding.display alone is generally unsafe. Consider using CodeableConcept.text

Elements defined in Ancestors: id, extension
... systemΣ0..1uriIdentity of the terminology system
... versionΣ0..1stringVersion of the system - if relevant
... codeΣC0..1codeSymbol in syntax defined by the system
... userSelectedΣ0..1booleanIf this coding was chosen directly by the user

doco Documentation for this format icon

Definition: XML | JSON

XML Template

<Coding xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <system value="[uri]"/><!-- 0..1 Identity of the terminology system -->
 <version value="[string]"/><!-- 0..1 Version of the system - if relevant -->
 <code value="[code]"/><!-- I 0..1 Symbol in syntax defined by the system -->
 <display value="[string]"/><!-- I 0..1 Representation defined by the system -->
 <userSelected value="[boolean]"/><!-- 0..1 If this coding was chosen directly by the user -->
</Coding>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:system [ uri ] ; # 0..1 Identity of the terminology system
  fhir:version [ string ] ; # 0..1 Version of the system - if relevant
  fhir:code [ code ] ; # 0..1 I Symbol in syntax defined by the system
  fhir:display [ string ] ; # 0..1 I Representation defined by the system
  fhir:userSelected [ boolean ] ; # 0..1 If this coding was chosen directly by the user
]

Changes since Release 3

Changes from both R4 and R4B

Coding
  • No Changes

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. CodingΣNElementA reference to a code defined by a terminology system
+ Warning: A Coding SHOULD NOT have a display unless a code is also present. Computation on Coding.display alone is generally unsafe. Consider using CodeableConcept.text

Elements defined in Ancestors: id, extension
... systemΣ0..1uriIdentity of the terminology system
... versionΣ0..1stringVersion of the system - if relevant
... codeΣC0..1codeSymbol in syntax defined by the system
... userSelectedΣ0..1booleanIf this coding was chosen directly by the user

doco Documentation for this format icon

XML Template

<Coding xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <system value="[uri]"/><!-- 0..1 Identity of the terminology system -->
 <version value="[string]"/><!-- 0..1 Version of the system - if relevant -->
 <code value="[code]"/><!-- I 0..1 Symbol in syntax defined by the system -->
 <display value="[string]"/><!-- I 0..1 Representation defined by the system -->
 <userSelected value="[boolean]"/><!-- 0..1 If this coding was chosen directly by the user -->
</Coding>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:system [ uri ] ; # 0..1 Identity of the terminology system
  fhir:version [ string ] ; # 0..1 Version of the system - if relevant
  fhir:code [ code ] ; # 0..1 I Symbol in syntax defined by the system
  fhir:display [ string ] ; # 0..1 I Representation defined by the system
  fhir:userSelected [ boolean ] ; # 0..1 If this coding was chosen directly by the user
]

Changes since Release 3

Changes from both R4 and R4B

Coding
  • No Changes

See the Full Difference for further information

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 an absolute 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:

  • National releases of SNOMED CT (consistency of definitions varies amongst jurisdictions, and some jurisdictions may make their own rules on this)
  • Various versions of ICD (note: the major releases are labeled as different code systems altogether, but there is variation within versions)

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, by use of:

  • CodeSystem.concept.display
  • CodeSystem.concept.designation.value (including in supplements)

Note that displays defined in value sets (ValueSet.include.concept.display and ValueSet.include.concept.designation.value) are not allowed in Coding.display.

If one of the available display strings is labeled as preferred, it SHOULD be used (note that CodeSystem.concept.display is preferred for the base resource language if it is populated, but other display strings may be preferred in other languages, or for other usages). 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 concept. The implication of this is that implementers SHOULD never provide a system without a code unless this is the intended meaning AND it is appropriate for the code system and version. (E.g. the code system does not have an 'OTHER' concept.) This approach cannot be used if an appropriate code might exist within the code system but does not exist within the bound ValueSet.

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

idLevelLocationDescriptionExpression
img cod-1Warning (base)A Coding SHOULD NOT have a display unless a code is also present. Computation on Coding.display alone is generally unsafe. Consider using CodeableConcept.textcode.exists().not() implies display.exists().not()

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: Meta, DataRequirement, ElementDefinition, VirtualServiceDetail, UsageContext, Signature, CodeableConcept, ActivityDefinition, ActorDefinition, Appointment, AuditEvent, BiologicallyDerivedProduct, CanonicalResource, CapabilityStatement, ChargeItemDefinition, Citation, CodeSystem, CompartmentDefinition, ConceptMap, ConditionDefinition, Consent, Contract, DeviceDefinition, DocumentReference, EventDefinition, Evidence, EvidenceVariable, ExampleScenario, ExplanationOfBenefit, GraphDefinition, Group, ImplementationGuide, InventoryItem, Library, Location, Measure, MedicinalProductDefinition, MessageDefinition, MessageHeader, NamingSystem, ObservationDefinition, OperationDefinition, Permission, PlanDefinition, Questionnaire, QuestionnaireResponse, Requirements, SearchParameter, SpecimenDefinition, StructureDefinition, StructureMap, Subscription, SubscriptionTopic, TerminologyCapabilities, TestPlan, TestScript and ValueSet

Implementation Note: This specification defines two types for representing coded values:

  • Coding: a simple direct reference to a code defined by a code system
  • CodeableConcept: a text description and/or a list of Codings (i.e. a list of references to codes defined by code systems)

The Coding datatype 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 datatype 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.

FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Normative

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 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 datatype can be bound to a ValueSet.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. CodeableConceptΣNElementConcept - reference to a terminology or just text

Elements defined in Ancestors: id, extension
... codingΣ0..*CodingCode defined by a terminology system

... textΣT0..1stringPlain text representation of the concept

doco Documentation for this format icon

Definition: XML | JSON

XML Template

<CodeableConcept 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 -->
</CodeableConcept>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:coding  ( [ Coding ] ... ) ; # 0..* Code defined by a terminology system
  fhir:text [ string ] ; # 0..1 Plain text representation of the concept
]

Changes since Release 3

Changes from both R4 and R4B

CodeableConcept
  • No Changes

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. CodeableConceptΣNElementConcept - reference to a terminology or just text

Elements defined in Ancestors: id, extension
... codingΣ0..*CodingCode defined by a terminology system

... textΣT0..1stringPlain text representation of the concept

doco Documentation for this format icon

XML Template

<CodeableConcept 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 -->
</CodeableConcept>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:coding  ( [ Coding ] ... ) ; # 0..* Code defined by a terminology system
  fhir:text [ string ] ; # 0..1 Plain text representation of the concept
]

Changes since Release 3

Changes from both R4 and R4B

CodeableConcept
  • No Changes

See the Full Difference for further information

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. Even if a coding is flagged as user-selected, it is good practice to put the specific text the user chose in CodeableConcept.text.

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: DataRequirement, Dosage, RelativeTime, MonetaryComponent, MarketingStatus, Identifier, TriggerDefinition, RelatedArtifact, ProductShelfLife, UsageContext, CodeableReference, Timing, ExtendedContactDetail, Account, ActivityDefinition, ActorDefinition, AdministrableProductDefinition, AdverseEvent, AllergyIntolerance, Appointment, AppointmentResponse, ArtifactAssessment, AuditEvent, Basic, BiologicallyDerivedProduct, BiologicallyDerivedProductDispense, BodyStructure, CanonicalResource, CapabilityStatement, CarePlan, CareTeam, ChargeItem, ChargeItemDefinition, Citation, Claim, ClaimResponse, ClinicalImpression, ClinicalUseDefinition, CodeSystem, Communication, CommunicationRequest, Composition, ConceptMap, Condition, ConditionDefinition, Consent, Contract, Coverage, CoverageEligibilityRequest, CoverageEligibilityResponse, DetectedIssue, Device, DeviceAssociation, DeviceDefinition, DeviceDispense, DeviceMetric, DeviceRequest, DeviceUsage, DiagnosticReport, DocumentReference, Encounter, EncounterHistory, Endpoint, EpisodeOfCare, EventDefinition, Evidence, EvidenceReport, EvidenceVariable, ExampleScenario, ExplanationOfBenefit, FamilyMemberHistory, Flag, FormularyItem, GenomicStudy, Goal, GraphDefinition, Group, GuidanceResponse, HealthcareService, ImagingSelection, ImagingStudy, Immunization, ImmunizationEvaluation, ImmunizationRecommendation, ImplementationGuide, Ingredient, InsurancePlan, InsuranceProduct, InventoryItem, InventoryReport, Invoice, Library, List, Location, ManufacturedItemDefinition, Measure, MeasureReport, Medication, MedicationAdministration, MedicationDispense, MedicationKnowledge, MedicationRequest, MedicationStatement, MedicinalProductDefinition, MessageDefinition, MessageHeader, MetadataResource, MolecularSequence, NamingSystem, NutritionIntake, NutritionOrder, NutritionProduct, Observation, ObservationDefinition, OperationDefinition, OperationOutcome, Organization, OrganizationAffiliation, PackagedProductDefinition, Patient, PaymentNotice, PaymentReconciliation, Permission, Person, PlanDefinition, Practitioner, PractitionerRole, Procedure, Provenance, Questionnaire, RegulatedAuthorization, RelatedPerson, RequestOrchestration, Requirements, ResearchStudy, ResearchSubject, RiskAssessment, Schedule, SearchParameter, ServiceRequest, Slot, Specimen, SpecimenDefinition, StructureDefinition, StructureMap, SubscriptionStatus, SubscriptionTopic, Substance, SubstanceDefinition, SubstanceNucleicAcid, SubstancePolymer, SubstanceProtein, SubstanceReferenceInformation, SubstanceSourceMaterial, SupplyDelivery, SupplyRequest, Task, TerminologyCapabilities, TestPlan, TestScript, Transport, ValueSet, VerificationResult and VisionPrescription

FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Normative

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 Conversions

A measured amount (or an amount that can potentially be measured).

This datatype can be bound to a ValueSet.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. QuantityΣNElementA measured or measurable amount
+ Rule: If a code for the unit is present, the system SHALL also be present

Elements defined in Ancestors: id, extension
... valueΣ0..1decimalNumerical value (with implicit precision)
... comparator?!Σ0..1code< | <= | >= | > | ad - how to understand the value
Binding: QuantityComparator (Required)
... unitΣT0..1stringUnit representation
... codeΣC0..1codeCoded form of the unit

doco Documentation for this format icon

Definition: XML | JSON

XML Template

<Quantity xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <value value="[decimal]"/><!-- 0..1 Numerical value (with implicit precision) -->
 <comparator value="[code]"/><!-- 0..1 < | <= | >= | > | ad - how to understand the value -->
 <unit value="[string]"/><!-- 0..1 Unit representation -->
 <system value="[uri]"/><!-- I 0..1 System that defines coded unit form -->
 <code value="[code]"/><!-- I 0..1 Coded form of the unit -->
</Quantity>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:value [ decimal ] ; # 0..1 Numerical value (with implicit precision)
  fhir:comparator [ code ] ; # 0..1 < | <= | >= | > | ad - how to understand the value
  fhir:unit [ string ] ; # 0..1 Unit representation
  fhir:system [ uri ] ; # 0..1 I System that defines coded unit form
  fhir:code [ code ] ; # 0..1 I Coded form of the unit
]

Changes since Release 3

Changes from both R4 and R4B

Quantity
Quantity.comparator
  • Add code ad

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. QuantityΣNElementA measured or measurable amount
+ Rule: If a code for the unit is present, the system SHALL also be present

Elements defined in Ancestors: id, extension
... valueΣ0..1decimalNumerical value (with implicit precision)
... comparator?!Σ0..1code< | <= | >= | > | ad - how to understand the value
Binding: QuantityComparator (Required)
... unitΣT0..1stringUnit representation
... codeΣC0..1codeCoded form of the unit

doco Documentation for this format icon

XML Template

<Quantity xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <value value="[decimal]"/><!-- 0..1 Numerical value (with implicit precision) -->
 <comparator value="[code]"/><!-- 0..1 < | <= | >= | > | ad - how to understand the value -->
 <unit value="[string]"/><!-- 0..1 Unit representation -->
 <system value="[uri]"/><!-- I 0..1 System that defines coded unit form -->
 <code value="[code]"/><!-- I 0..1 Coded form of the unit -->
</Quantity>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:value [ decimal ] ; # 0..1 Numerical value (with implicit precision)
  fhir:comparator [ code ] ; # 0..1 < | <= | >= | > | ad - how to understand the value
  fhir:unit [ string ] ; # 0..1 Unit representation
  fhir:system [ uri ] ; # 0..1 I System that defines coded unit form
  fhir:code [ code ] ; # 0..1 I Coded form of the unit
]

Changes since Release 3

Changes from both R4 and R4B

Quantity
Quantity.comparator
  • Add code ad

See the Full Difference for further information

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

idLevelLocationDescriptionExpression
img qty-3Rule (base)If a code for the unit is present, the system SHALL also be presentcode.empty() or system.exists()

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.

Terminology Bindings

PathValueSetTypeDocumentation
Quantity.comparator QuantityComparator Required

How the Quantity should be understood and represented.

Quantity is used in the following places: Count, Ratio, ElementDefinition, Distance, Age, Duration, UsageContext, AdministrableProductDefinition, ArtifactAssessment, AuditEvent, BiologicallyDerivedProduct, BodyStructure, ChargeItem, Claim, ClaimResponse, ConceptMap, ConditionDefinition, Contract, Device, DeviceDefinition, DeviceMetric, DeviceRequest, Evidence, EvidenceReport, EvidenceVariable, ExplanationOfBenefit, Goal, Group, HealthcareService, Ingredient, InsurancePlan, InsuranceProduct, InventoryItem, InventoryReport, ManufacturedItemDefinition, MeasureReport, Medication, MedicationKnowledge, MedicinalProductDefinition, Observation, PackagedProductDefinition, PlanDefinition, Questionnaire, ServiceRequest, SubstanceDefinition, SubstancePolymer, SubstanceReferenceInformation and SupplyRequest

There are several additional datatypes that are specializations of Quantity that only introduce new restrictions on the existing elements defined as part of the Quantity datatype.

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 icon).

Type Name Rules Formal Definitions
Distance
idLevelLocationDescriptionExpression
img dis-1Rule (base)There SHALL be a code if there is a value and it SHALL be an expression of length. If system is present, it SHALL be UCUM.(code.exists() or value.empty()) and (system.empty() or system = %ucum)

Terminology Bindings

PathValueSetTypeDocumentation
Distance CommonUCUMCodesForDistance Extensible

Unified Code for Units of Measure (UCUM). This value set includes all common UCUM codes used for distance - that it is, all commonly used units which have the same canonical unit as 'm' (meter)

  All UCUM Expression for Distance maximum

XML, JSON
Usage: (not used as yet)

Implementation Note: 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
idLevelLocationDescriptionExpression
img age-1Rule (base)There SHALL be a code if there is a value and it SHALL be an expression of time. If system is present, it SHALL be UCUM. If value is present, it SHALL be positive.(code.exists() or value.empty()) and (system.empty() or system = %ucum) and (value.empty() or value.hasValue().not() or value > 0)

Terminology Bindings

PathValueSetTypeDocumentation
Age CommonUCUMCodesForAge Extensible

Unified Code for Units of Measure (UCUM). This value set includes all common UCUM codes used for Age - that it is, all commonly used units which have the same canonical unit as 'a' (year)

  All UCUM Expression for Time maximum

XML, JSON
Note: Age intentionally carries the semantics of a duration of time during which an organism (or a process) has existed.
Usage: ActivityDefinition, AllergyIntolerance, Condition, FamilyMemberHistory, PlanDefinition, Procedure and RequestOrchestration
Count
idLevelLocationDescriptionExpression
img cnt-3Rule (base)There SHALL be a code with a value of "1" if there is a value. If system is present, it SHALL be UCUM. If present, the value SHALL be a whole number.(code.exists() or value.empty()) and (system.empty() or system = %ucum) and (code.empty() or code = '1') and (value.empty() or value.hasValue().not() or value.toString().contains('.').not())
XML, JSON
Usage: Device
Duration
idLevelLocationDescriptionExpression
img drt-1Rule (base)There SHALL be a code if there is a value and it SHALL be an expression of time. If system is present, it SHALL be UCUM.code.exists() implies ((system = %ucum) and value.exists())

Terminology Bindings

PathValueSetTypeDocumentation
Duration CommonUCUMCodesForDuration Extensible

Unified Code for Units of Measure (UCUM). This value set includes all common UCUM codes used for Duration - that it is, all commonly used units which have the same canonical unit as 'a' (year)

  All UCUM Expression for Time maximum

XML, JSON
Note: Duration intentionally carries the semantics of a length of time.
Usage: DataRequirement, RelativeTime, ProductShelfLife, Timing, ActivityDefinition, AdministrableProductDefinition, Device, Encounter, EncounterHistory, Goal, Group, InventoryItem, MeasureReport, MedicationKnowledge, MedicationRequest, PlanDefinition, RequestOrchestration, Specimen and SpecimenDefinition

In addition to the specializations, there is one constraint on Quantity used in several resources:

Profile Name Rules Formal Definitions
Simple Quantity
idLevelLocationDescriptionExpression
sqty-1Rule(base)The comparator is not used on a SimpleQuantitycomparator.empty()
XML, JSON
Usage: Dosage, RatioRange, SampledData, Ratio, Range, ActivityDefinition, BiologicallyDerivedProductDispense, Claim, ClaimResponse, Contract, Coverage, CoverageEligibilityRequest, DeviceDispense, Evidence, ExplanationOfBenefit, Immunization, InventoryItem, MedicationAdministration, MedicationDispense, MedicationKnowledge, MedicationRequest, NutritionIntake, NutritionOrder, NutritionProduct, Observation, QuestionnaireResponse, Specimen, SpecimenDefinition, Substance, SupplyDelivery and VisionPrescription

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.

FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Normative

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 Conversions

An amount of currency.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. MoneyΣNElementAn amount of economic utility in some recognized currency

Elements defined in Ancestors: id, extension
... valueΣ0..1decimalNumerical value (with implicit precision)
... currencyΣ0..1codeISO 4217 Currency Code
Binding: Currencies (Required)

doco Documentation for this format icon

Definition: XML | JSON

XML Template

<Money xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <value value="[decimal]"/><!-- 0..1 Numerical value (with implicit precision) -->
 <currency value="[code]"/><!-- 0..1 ISO 4217 Currency Code -->
</Money>

JSON Template

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:value [ decimal ] ; # 0..1 Numerical value (with implicit precision)
  fhir:currency [ code ] ; # 0..1 ISO 4217 Currency Code
]

Changes since Release 3

Changes from both R4 and R4B

Money
  • No Changes

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. MoneyΣNElementAn amount of economic utility in some recognized currency

Elements defined in Ancestors: id, extension
... valueΣ0..1decimalNumerical value (with implicit precision)
... currencyΣ0..1codeISO 4217 Currency Code
Binding: Currencies (Required)

doco Documentation for this format icon

XML Template

<Money xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <value value="[decimal]"/><!-- 0..1 Numerical value (with implicit precision) -->
 <currency value="[code]"/><!-- 0..1 ISO 4217 Currency Code -->
</Money>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:value [ decimal ] ; # 0..1 Numerical value (with implicit precision)
  fhir:currency [ code ] ; # 0..1 ISO 4217 Currency Code
]

Changes since Release 3

Changes from both R4 and R4B

Money
  • No Changes

See the Full Difference for further information

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: MonetaryComponent, Account, Claim, ClaimResponse, Contract, Coverage, CoverageEligibilityRequest, CoverageEligibilityResponse, ExplanationOfBenefit, InsurancePlan, Invoice, MedicationKnowledge, PaymentNotice and PaymentReconciliation

There are also circumstances where a financial amount must be represented as the numerator or denominator 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
idLevelLocationDescriptionExpression
mtqy-1Rule(base)There SHALL be a code if there is a value and it SHALL be an expression of currency. If system is present, it SHALL be ISO 4217 (system = "urn:iso:std:iso:4217" - currency).(code.exists() or value.empty()) and (system.empty() or system = 'urn:iso:std:iso:4217')
XML, JSON
Usage: (not used as yet)

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.

FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Normative

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 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.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. RangeΣNElementSet of values bounded by low and high
+ Rule: If present, low SHALL have a lower value than high

Elements defined in Ancestors: id, extension
... lowΣC0..1SimpleQuantityLow limit
... highΣC0..1SimpleQuantityHigh limit

doco Documentation for this format icon

Definition: XML | JSON

XML Template

<Range xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <low><!-- I 0..1 Quantity(SimpleQuantity) Low limit --></low>
 <high><!-- I 0..1 Quantity(SimpleQuantity) High limit --></high>
</Range>

JSON Template

{doco
  // from Element: extension
  "low" : { Quantity(SimpleQuantity) }, // I Low limit
  "high" : { Quantity(SimpleQuantity) } // I High limit
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:low [ Quantity(SimpleQuantity) ] ; # 0..1 I Low limit
  fhir:high [ Quantity(SimpleQuantity) ] ; # 0..1 I High limit
]

Changes since Release 3

Changes from both R4 and R4B

Range
  • No Changes

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. RangeΣNElementSet of values bounded by low and high
+ Rule: If present, low SHALL have a lower value than high

Elements defined in Ancestors: id, extension
... lowΣC0..1SimpleQuantityLow limit
... highΣC0..1SimpleQuantityHigh limit

doco Documentation for this format icon

XML Template

<Range xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <low><!-- I 0..1 Quantity(SimpleQuantity) Low limit --></low>
 <high><!-- I 0..1 Quantity(SimpleQuantity) High limit --></high>
</Range>

JSON Template

{doco
  // from Element: extension
  "low" : { Quantity(SimpleQuantity) }, // I Low limit
  "high" : { Quantity(SimpleQuantity) } // I High limit
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:low [ Quantity(SimpleQuantity) ] ; # 0..1 I Low limit
  fhir:high [ Quantity(SimpleQuantity) ] ; # 0..1 I High limit
]

Changes since Release 3

Changes from both R4 and R4B

Range
  • No Changes

See the Full Difference for further information

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

idLevelLocationDescriptionExpression
img rng-2Rule (base)If present, low SHALL have a lower value than highlow.value.empty() or high.value.empty() or low.lowBoundary().comparable(high.highBoundary()).not() or (low.lowBoundary() <= high.highBoundary())

Range is used in the following places: Dosage, RelativeTime, UsageContext, Timing, ActivityDefinition, AllergyIntolerance, AuditEvent, BiologicallyDerivedProduct, ClinicalUseDefinition, Condition, Device, DeviceDefinition, DeviceRequest, Evidence, EvidenceReport, EvidenceVariable, FamilyMemberHistory, Goal, Group, HealthcareService, InventoryItem, MeasureReport, MedicationKnowledge, MolecularSequence, Observation, ObservationDefinition, PlanDefinition, Procedure, RequestOrchestration, RiskAssessment, ServiceRequest, SpecimenDefinition, SubstanceReferenceInformation and SupplyRequest

FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Normative

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 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.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. RatioΣNElementA ratio of two Quantity values - a numerator and a denominator
+ Rule: Numerator and denominator SHALL both be present, or both are absent. If both are absent, there SHALL be some extension present

Elements defined in Ancestors: id, extension
... numeratorΣC0..1QuantityNumerator value
... denominatorΣC0..1SimpleQuantityDenominator value

doco Documentation for this format icon

Definition: XML | JSON

XML Template

<Ratio xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <numerator><!-- I 0..1 Quantity Numerator value --></numerator>
 <denominator><!-- I 0..1 Quantity(SimpleQuantity) Denominator value --></denominator>
</Ratio>

JSON Template

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:numerator [ Quantity ] ; # 0..1 I Numerator value
  fhir:denominator [ Quantity(SimpleQuantity) ] ; # 0..1 I Denominator value
]

Changes since Release 3

Changes from both R4 and R4B

Ratio
Ratio.denominator
  • Type changed from Quantity to Quantity(http://hl7.org/fhir/StructureDefinition/SimpleQuantity)

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. RatioΣNElementA ratio of two Quantity values - a numerator and a denominator
+ Rule: Numerator and denominator SHALL both be present, or both are absent. If both are absent, there SHALL be some extension present

Elements defined in Ancestors: id, extension
... numeratorΣC0..1QuantityNumerator value
... denominatorΣC0..1SimpleQuantityDenominator value

doco Documentation for this format icon

XML Template

<Ratio xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <numerator><!-- I 0..1 Quantity Numerator value --></numerator>
 <denominator><!-- I 0..1 Quantity(SimpleQuantity) Denominator value --></denominator>
</Ratio>

JSON Template

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:numerator [ Quantity ] ; # 0..1 I Numerator value
  fhir:denominator [ Quantity(SimpleQuantity) ] ; # 0..1 I Denominator value
]

Changes since Release 3

Changes from both R4 and R4B

Ratio
Ratio.denominator
  • Type changed from Quantity to Quantity(http://hl7.org/fhir/StructureDefinition/SimpleQuantity)

See the Full Difference for further information

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

idLevelLocationDescriptionExpression
img rat-1Rule (base)Numerator and denominator SHALL both be present, or both are absent. If both are absent, there SHALL be some extension present(numerator.exists() and denominator.exists()) or (numerator.empty() and denominator.empty() and extension.exists())

The context of use may require particular types of Quantity for the numerator or denominator.

Ratio is used in the following places: Dosage, AdministrableProductDefinition, AuditEvent, BiologicallyDerivedProduct, Goal, Ingredient, InventoryItem, Medication, MedicationAdministration, MedicationKnowledge, NutritionOrder, NutritionProduct, Observation, PlanDefinition, ServiceRequest, Substance and SubstanceDefinition

FHIR Infrastructure icon Work GroupMaturity Level: 3Standards Status: Trial Use

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 Conversions

A range of ratios of two Quantity values expressed as a low numerator, a high numerator, and a denominator.

The RatioRange datatype should only be used to express a range of ratios if the relationship cannot be suitably expressed using a Range and a common unit. Where the denominator value is known to be fixed to "1", Range should be used instead of RatioRange.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. RatioRangeΣTUElementRange of ratio values
+ Rule: One of lowNumerator or highNumerator and denominator SHALL be present, or all are absent. If all are absent, there SHALL be some extension present
+ Rule: If present, lowNumerator SHALL have a lower value than highNumerator

Elements defined in Ancestors: id, extension
... lowNumeratorΣC0..1SimpleQuantityLow Numerator limit
... highNumeratorΣC0..1SimpleQuantityHigh Numerator limit
... denominatorΣC0..1SimpleQuantityDenominator value

doco Documentation for this format icon

Definition: XML | JSON

XML Template

<RatioRange xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <lowNumerator><!-- I 0..1 Quantity(SimpleQuantity) Low Numerator limit --></lowNumerator>
 <highNumerator><!-- I 0..1 Quantity(SimpleQuantity) High Numerator limit --></highNumerator>
 <denominator><!-- I 0..1 Quantity(SimpleQuantity) Denominator value --></denominator>
</RatioRange>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:lowNumerator [ Quantity(SimpleQuantity) ] ; # 0..1 I Low Numerator limit
  fhir:highNumerator [ Quantity(SimpleQuantity) ] ; # 0..1 I High Numerator limit
  fhir:denominator [ Quantity(SimpleQuantity) ] ; # 0..1 I Denominator value
]

Changes since Release 3

Changes from both R4 and R4B

This complex-type did not exist in Release R4

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. RatioRangeΣTUElementRange of ratio values
+ Rule: One of lowNumerator or highNumerator and denominator SHALL be present, or all are absent. If all are absent, there SHALL be some extension present
+ Rule: If present, lowNumerator SHALL have a lower value than highNumerator

Elements defined in Ancestors: id, extension
... lowNumeratorΣC0..1SimpleQuantityLow Numerator limit
... highNumeratorΣC0..1SimpleQuantityHigh Numerator limit
... denominatorΣC0..1SimpleQuantityDenominator value

doco Documentation for this format icon

XML Template

<RatioRange xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <lowNumerator><!-- I 0..1 Quantity(SimpleQuantity) Low Numerator limit --></lowNumerator>
 <highNumerator><!-- I 0..1 Quantity(SimpleQuantity) High Numerator limit --></highNumerator>
 <denominator><!-- I 0..1 Quantity(SimpleQuantity) Denominator value --></denominator>
</RatioRange>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:lowNumerator [ Quantity(SimpleQuantity) ] ; # 0..1 I Low Numerator limit
  fhir:highNumerator [ Quantity(SimpleQuantity) ] ; # 0..1 I High Numerator limit
  fhir:denominator [ Quantity(SimpleQuantity) ] ; # 0..1 I Denominator value
]

Changes since Release 3

Changes from both R4 and R4B

This complex-type did not exist in Release R4

See the Full Difference for further information

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 range has one of the numerators and a denominator; however, these are not mandatory in order to allow an invalid ratio with an extension with further information.

Constraints

idLevelLocationDescriptionExpression
img ratrng-1Rule (base)One of lowNumerator or highNumerator and denominator SHALL be present, or all are absent. If all are absent, there SHALL be some extension present((lowNumerator.exists() or highNumerator.exists()) and denominator.exists()) or (lowNumerator.empty() and highNumerator.empty() and denominator.empty() and extension.exists())
img ratrng-2Rule (base)If present, lowNumerator SHALL have a lower value than highNumeratorlowNumerator.hasValue().not() or highNumerator.hasValue().not() or (lowNumerator.lowBoundary() <= highNumerator.highBoundary())

The context of use may require particular types of Quantity for the numerators or denominator.

RatioRange is used in the following places: Ingredient

FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Normative

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 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").

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. PeriodΣNElementTime range defined by start and end date/time
+ Rule: If present, start SHALL have a lower or equal value than end

Elements defined in Ancestors: id, extension
... startΣC0..1dateTimeStarting time with inclusive boundary
... endΣC0..1dateTimeEnd time with inclusive boundary, if not ongoing

doco Documentation for this format icon

Definition: XML | JSON

XML Template

<Period xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <start value="[dateTime]"/><!-- I 0..1 Starting time with inclusive boundary -->
 <end value="[dateTime]"/><!-- I 0..1 End time with inclusive boundary, if not ongoing -->
</Period>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:start [ dateTime ] ; # 0..1 I Starting time with inclusive boundary
  fhir:end [ dateTime ] ; # 0..1 I End time with inclusive boundary, if not ongoing
]

Changes since Release 3

Changes from both R4 and R4B

Period
  • No Changes

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. PeriodΣNElementTime range defined by start and end date/time
+ Rule: If present, start SHALL have a lower or equal value than end

Elements defined in Ancestors: id, extension
... startΣC0..1dateTimeStarting time with inclusive boundary
... endΣC0..1dateTimeEnd time with inclusive boundary, if not ongoing

doco Documentation for this format icon

XML Template

<Period xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <start value="[dateTime]"/><!-- I 0..1 Starting time with inclusive boundary -->
 <end value="[dateTime]"/><!-- I 0..1 End time with inclusive boundary, if not ongoing -->
</Period>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:start [ dateTime ] ; # 0..1 I Starting time with inclusive boundary
  fhir:end [ dateTime ] ; # 0..1 I End time with inclusive boundary, if not ongoing
]

Changes since Release 3

Changes from both R4 and R4B

Period
  • No Changes

See the Full Difference for further information

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. Alternatively, this may be represented by having an explicit end in the future, in which case this means the 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.

Constraints

idLevelLocationDescriptionExpression
img per-1Rule (base)If present, start SHALL have a lower or equal value than endstart.hasValue().not() or end.hasValue().not() or (start.lowBoundary() <= end.highBoundary())

Period is used in the following places: Address, DataRequirement, HumanName, ContactPoint, MarketingStatus, Identifier, Availability, Timing, ExtendedContactDetail, Account, ActivityDefinition, AdverseEvent, AllergyIntolerance, Appointment, AuditEvent, BiologicallyDerivedProduct, CarePlan, CareTeam, ChargeItem, ChargeItemDefinition, Citation, Claim, ClaimResponse, ClinicalImpression, CodeSystem, CommunicationRequest, Composition, ConceptMap, Condition, Consent, Contract, Coverage, CoverageEligibilityRequest, CoverageEligibilityResponse, DetectedIssue, DeviceAssociation, DeviceDefinition, DeviceRequest, DeviceUsage, DiagnosticReport, DocumentReference, Encounter, EncounterHistory, Endpoint, EpisodeOfCare, EventDefinition, EvidenceReport, EvidenceVariable, ExplanationOfBenefit, FamilyMemberHistory, Flag, Group, InsuranceProduct, InventoryReport, Invoice, Library, Measure, MeasureReport, MedicationAdministration, MedicationKnowledge, MedicationRequest, MedicationStatement, MedicinalProductDefinition, MetadataResource, NamingSystem, NutritionIntake, Observation, ObservationDefinition, Organization, OrganizationAffiliation, Patient, PaymentReconciliation, Permission, PlanDefinition, Practitioner, PractitionerRole, Procedure, Provenance, Questionnaire, RegulatedAuthorization, RelatedPerson, RequestOrchestration, ResearchStudy, ResearchSubject, RiskAssessment, Schedule, ServiceRequest, Specimen, SpecimenDefinition, SubscriptionTopic, SupplyDelivery, SupplyRequest, Task, Transport and ValueSet

FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Trial Use

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 Conversions

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 datatype includes a series of raw decimal values (which are mostly simple integers) or codes, along with adjustments for scale and factor. These are interpreted such that

original measured value[i] = SampledData.data[i] * SampledData.factor + SampledData.origin.value

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. SampledDataTUElementA series of measurements taken by a device
+ Rule: A SampledData SAHLL have either an interval and offsets but not both

Elements defined in Ancestors: id, extension
... originΣ1..1SimpleQuantityZero value and units
... intervalΣC0..1decimalNumber of intervalUnits between samples
... intervalUnitΣ1..1codeThe measurement unit of the interval between samples
Binding: UCUM Codes (Required)
... lowerLimitΣ0..1decimalLower limit of detection
... upperLimitΣ0..1decimalUpper limit of detection
... dimensionsΣ1..1positiveIntNumber of sample points at each time point
... codeMap0..1canonical(ConceptMap)Defines the codes used in the data
... offsetsC0..1stringOffsets, typically in time, at which data values were taken
... data0..1stringDecimal values with spaces, or "E" | "U" | "L", or another code

doco Documentation for this format icon

Definition: XML | JSON

UML Diagram (Legend)

SampledDataThe base quantity that a measured value of zero represents. In addition, this provides the units of the entire measurement seriesorigin : Quantity(SimpleQuantity) [1..1]Amount of intervalUnits between samples, e.g. milliseconds for time-based samplinginterval : decimal [0..1] « This element has or is affected by some invariantsC »The measurement unit in which the sample interval is expressedintervalUnit : code [1..1] « Units of measure allowed for an element. (Strength=Required)UCUMCodes! »A correction factor that is applied to the sampled data points before they are added to the originfactor : decimal [0..1]The lower limit of detection of the measured points. This is needed if any of the data points have the value "L" (lower than detection limit)lowerLimit : decimal [0..1]The upper limit of detection of the measured points. This is needed if any of the data points have the value "U" (higher than detection limit)upperLimit : decimal [0..1]The number of sample points at each time point. If this value is greater than one, then the dimensions will be interlaced - all the sample points for a point in time will be recorded at oncedimensions : positiveInt [1..1]Reference to ConceptMap that defines the codes used in the datacodeMap : canonical [0..1] « ConceptMap »A series of data points which are decimal values separated by a single space (character u20). The units in which the offsets are expressed are found in intervalUnit. The absolute point at which the measurements begin SHALL be conveyed outside the scope of this datatype, e.g. Observation.effectiveDateTime for a timing offsetoffsets : string [0..1] « This element has or is affected by some invariantsC »A series of data points which are decimal values or codes separated by a single space (character u20). The special codes "E" (error), "L" (below detection limit) and "U" (above detection limit) are also defined for used in place of decimal valuesdata : string [0..1]DataType

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:origin [ Quantity(SimpleQuantity) ] ; # 1..1 Zero value and units
  fhir:interval [ decimal ] ; # 0..1 I Number of intervalUnits between samples
  fhir:intervalUnit [ code ] ; # 1..1 The measurement unit of the interval between samples
  fhir:factor [ decimal ] ; # 0..1 Multiply data by this before adding to origin
  fhir:lowerLimit [ decimal ] ; # 0..1 Lower limit of detection
  fhir:upperLimit [ decimal ] ; # 0..1 Upper limit of detection
  fhir:dimensions [ positiveInt ] ; # 1..1 Number of sample points at each time point
  fhir:codeMap [ canonical(ConceptMap) ] ; # 0..1 Defines the codes used in the data
  fhir:offsets [ string ] ; # 0..1 I Offsets, typically in time, at which data values were taken
  fhir:data [ string ] ; # 0..1 Decimal values with spaces, or "E" | "U" | "L", or another code
]

Changes since Release 3

Changes from both R4 and R4B

SampledData
SampledData.interval
  • Added Element
SampledData.intervalUnit
  • Added Mandatory Element
SampledData.codeMap
  • Added Element
SampledData.offsets
  • Added Element
SampledData.period
  • Deleted (-> interval)

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. SampledDataTUElementA series of measurements taken by a device
+ Rule: A SampledData SAHLL have either an interval and offsets but not both

Elements defined in Ancestors: id, extension
... originΣ1..1SimpleQuantityZero value and units
... intervalΣC0..1decimalNumber of intervalUnits between samples
... intervalUnitΣ1..1codeThe measurement unit of the interval between samples
Binding: UCUM Codes (Required)
... lowerLimitΣ0..1decimalLower limit of detection
... upperLimitΣ0..1decimalUpper limit of detection
... dimensionsΣ1..1positiveIntNumber of sample points at each time point
... codeMap0..1canonical(ConceptMap)Defines the codes used in the data
... offsetsC0..1stringOffsets, typically in time, at which data values were taken
... data0..1stringDecimal values with spaces, or "E" | "U" | "L", or another code

doco Documentation for this format icon

UML Diagram (Legend)

SampledDataThe base quantity that a measured value of zero represents. In addition, this provides the units of the entire measurement seriesorigin : Quantity(SimpleQuantity) [1..1]Amount of intervalUnits between samples, e.g. milliseconds for time-based samplinginterval : decimal [0..1] « This element has or is affected by some invariantsC »The measurement unit in which the sample interval is expressedintervalUnit : code [1..1] « Units of measure allowed for an element. (Strength=Required)UCUMCodes! »A correction factor that is applied to the sampled data points before they are added to the originfactor : decimal [0..1]The lower limit of detection of the measured points. This is needed if any of the data points have the value "L" (lower than detection limit)lowerLimit : decimal [0..1]The upper limit of detection of the measured points. This is needed if any of the data points have the value "U" (higher than detection limit)upperLimit : decimal [0..1]The number of sample points at each time point. If this value is greater than one, then the dimensions will be interlaced - all the sample points for a point in time will be recorded at oncedimensions : positiveInt [1..1]Reference to ConceptMap that defines the codes used in the datacodeMap : canonical [0..1] « ConceptMap »A series of data points which are decimal values separated by a single space (character u20). The units in which the offsets are expressed are found in intervalUnit. The absolute point at which the measurements begin SHALL be conveyed outside the scope of this datatype, e.g. Observation.effectiveDateTime for a timing offsetoffsets : string [0..1] « This element has or is affected by some invariantsC »A series of data points which are decimal values or codes separated by a single space (character u20). The special codes "E" (error), "L" (below detection limit) and "U" (above detection limit) are also defined for used in place of decimal valuesdata : string [0..1]DataType

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:origin [ Quantity(SimpleQuantity) ] ; # 1..1 Zero value and units
  fhir:interval [ decimal ] ; # 0..1 I Number of intervalUnits between samples
  fhir:intervalUnit [ code ] ; # 1..1 The measurement unit of the interval between samples
  fhir:factor [ decimal ] ; # 0..1 Multiply data by this before adding to origin
  fhir:lowerLimit [ decimal ] ; # 0..1 Lower limit of detection
  fhir:upperLimit [ decimal ] ; # 0..1 Upper limit of detection
  fhir:dimensions [ positiveInt ] ; # 1..1 Number of sample points at each time point
  fhir:codeMap [ canonical(ConceptMap) ] ; # 0..1 Defines the codes used in the data
  fhir:offsets [ string ] ; # 0..1 I Offsets, typically in time, at which data values were taken
  fhir:data [ string ] ; # 0..1 Decimal values with spaces, or "E" | "U" | "L", or another code
]

Changes since Release 3

Changes from both R4 and R4B

SampledData
SampledData.interval
  • Added Element
SampledData.intervalUnit
  • Added Mandatory Element
SampledData.codeMap
  • Added Element
SampledData.offsets
  • Added Element
SampledData.period
  • Deleted (-> interval)

See the Full Difference for further information

SampledData supports multi-dimensional data, where there is more than one measurement for each time point. If there is more than one dimension, the different dimensions are interlaced - all the data points for a particular time are represented together.

Data points are separated by by a single space (Unicode character u20). Each data point is either a decimal value or a code. Three special codes are defined:

  • E: error - no valid measurement available for this data point
  • L: below detection point - the value was below the device's detection limit (lowerLimit, which must be provided if this code is used)
  • U: above detection point - the value was above the device's detection limit (upperLimit, which must be provided if this code is used)

Other codes may be used. In this case, the meaning of the codes is specified by the codeMap property which references a ConceptMap that defines the codes used in the data, and maps the codes to properly defined concepts in a CodeSystem. Note that in this case, source system defined in the ConceptMap is not used in the SampledData and is ignored. There SHALL only be one group in the ConceptMap. The ConceptMap cannot define meanings for any numerical values, nor for the codes 'E', 'U', or 'L' (nor, for safety, 'e', 'u', or 'l'), since they always have the meaning as defined above. There is no escape sequences; codes cannot contain spaces. Also, to make parsing simpler, codes cannot start with numerals.

SampledData is used in the following places: Observation

FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Normative

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 Conversions

A string, typically numeric or alphanumeric, 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.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. IdentifierΣNElementAn identifier intended for computation
+ Warning: Identifier with no value has limited utility. If communicating that an identifier value has been suppressed or missing, the value element SHOULD be present with an extension indicating the missing semantic - e.g. data-absent-reason

Elements defined in Ancestors: id, extension
... use?!Σ0..1codeusual | official | temp | secondary | old (If known)
Binding: IdentifierUse (Required)
... typeΣ0..1CodeableConceptDescription of identifier
Binding: Identifier Type Codes (Extensible)
... systemΣ0..1uriThe namespace for the identifier value
... periodΣ0..1PeriodTime period when id is/was valid for use
... assignerΣ0..1Reference(Organization)Organization that issued id (may be just text)

doco Documentation for this format icon

Definition: XML | JSON

XML Template

<Identifier xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <use value="[code]"/><!-- 0..1 usual | official | temp | secondary | old (If known) -->
 <type><!-- 0..1 CodeableConcept Description of identifier --></type>
 <system value="[uri]"/><!-- 0..1 The namespace for the identifier value -->
 <value value="[string]"/><!-- I 0..1 The value that is unique -->
 <period><!-- 0..1 Period Time period when id is/was valid for use --></period>
 <assigner><!-- 0..1 Reference(Organization) Organization that issued id (may be just text) --></assigner>
</Identifier>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:use [ code ] ; # 0..1 usual | official | temp | secondary | old (If known)
  fhir:type [ CodeableConcept ] ; # 0..1 Description of identifier
  fhir:system [ uri ] ; # 0..1 The namespace for the identifier value
  fhir:value [ string ] ; # 0..1 I The value that is unique
  fhir:period [ Period ] ; # 0..1 Time period when id is/was valid for use
  fhir:assigner [ Reference(Organization) ] ; # 0..1 Organization that issued id (may be just text)
]

Changes since Release 3

Changes from both R4 and R4B

Identifier
  • No Changes

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. IdentifierΣNElementAn identifier intended for computation
+ Warning: Identifier with no value has limited utility. If communicating that an identifier value has been suppressed or missing, the value element SHOULD be present with an extension indicating the missing semantic - e.g. data-absent-reason

Elements defined in Ancestors: id, extension
... use?!Σ0..1codeusual | official | temp | secondary | old (If known)
Binding: IdentifierUse (Required)
... typeΣ0..1CodeableConceptDescription of identifier
Binding: Identifier Type Codes (Extensible)
... systemΣ0..1uriThe namespace for the identifier value
... periodΣ0..1PeriodTime period when id is/was valid for use
... assignerΣ0..1Reference(Organization)Organization that issued id (may be just text)

doco Documentation for this format icon

XML Template

<Identifier xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <use value="[code]"/><!-- 0..1 usual | official | temp | secondary | old (If known) -->
 <type><!-- 0..1 CodeableConcept Description of identifier --></type>
 <system value="[uri]"/><!-- 0..1 The namespace for the identifier value -->
 <value value="[string]"/><!-- I 0..1 The value that is unique -->
 <period><!-- 0..1 Period Time period when id is/was valid for use --></period>
 <assigner><!-- 0..1 Reference(Organization) Organization that issued id (may be just text) --></assigner>
</Identifier>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:use [ code ] ; # 0..1 usual | official | temp | secondary | old (If known)
  fhir:type [ CodeableConcept ] ; # 0..1 Description of identifier
  fhir:system [ uri ] ; # 0..1 The namespace for the identifier value
  fhir:value [ string ] ; # 0..1 I The value that is unique
  fhir:period [ Period ] ; # 0..1 Time period when id is/was valid for use
  fhir:assigner [ Reference(Organization) ] ; # 0..1 Organization that issued id (may be just text)
]

Changes since Release 3

Changes from both R4 and R4B

Identifier
  • No Changes

See the Full Difference for further information

The system is an absolute 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) values
  • http://ns.electronichealth.net.au/id/hi/ihi/1.0 for Australian Individual Healthcare Identifier (IHI) numbers
  • urn:ietf:rfc:3986 for when the value of the identifier is itself a globally unique URI

If 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 icon 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.

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.

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). Naturally globally unique identifiers are those for which no other system has been assigned and where the value of the identifier is reasonably expected to not be re-used. Typically, these are absolute URIs of some kind.

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. Whether or not the proper Identifier.system is known, the human-readable label for the Identifier.value typically appears in Identifier.type.text. E.g. 'BC provincial health number'.

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

idLevelLocationDescriptionExpression
img ident-1Warning (base)Identifier with no value has limited utility. If communicating that an identifier value has been suppressed or missing, the value element SHOULD be present with an extension indicating the missing semantic - e.g. data-absent-reasonvalue.exists()

Terminology Bindings

PathValueSetTypeDocumentation
Identifier.use IdentifierUse Required

Identifies the purpose for this identifier, if known .

Identifier.type IdentifierTypeCodes Extensible

A coded type for an identifier that can be used to determine which identifier to use for a specific purpose.

Identifier is used in the following places: Reference, Account, ActivityDefinition, ActorDefinition, AdministrableProductDefinition, AdverseEvent, AllergyIntolerance, Appointment, AppointmentResponse, ArtifactAssessment, Basic, BiologicallyDerivedProduct, BiologicallyDerivedProductDispense, BodyStructure, Bundle, CanonicalResource, CapabilityStatement, CarePlan, CareTeam, ChargeItem, ChargeItemDefinition, Citation, Claim, ClaimResponse, ClinicalImpression, ClinicalUseDefinition, CodeSystem, Communication, CommunicationRequest, Composition, ConceptMap, Condition, ConditionDefinition, Consent, Contract, Coverage, CoverageEligibilityRequest, CoverageEligibilityResponse, DetectedIssue, Device, DeviceAssociation, DeviceDefinition, DeviceDispense, DeviceMetric, DeviceRequest, DeviceUsage, DiagnosticReport, DocumentReference, Encounter, EncounterHistory, Endpoint, EnrollmentRequest, EnrollmentResponse, EpisodeOfCare, EventDefinition, Evidence, EvidenceReport, EvidenceVariable, ExampleScenario, ExplanationOfBenefit, FamilyMemberHistory, Flag, FormularyItem, GenomicStudy, Goal, GraphDefinition, Group, GuidanceResponse, HealthcareService, ImagingSelection, ImagingStudy, Immunization, ImmunizationEvaluation, ImmunizationRecommendation, ImplementationGuide, Ingredient, InsurancePlan, InsuranceProduct, InventoryItem, InventoryReport, Invoice, Library, List, Location, ManufacturedItemDefinition, Measure, MeasureReport, Medication, MedicationAdministration, MedicationDispense, MedicationKnowledge, MedicationRequest, MedicationStatement, MedicinalProductDefinition, MessageDefinition, MessageHeader, MolecularSequence, NamingSystem, NutritionIntake, NutritionOrder, NutritionProduct, Observation, ObservationDefinition, OperationDefinition, Organization, OrganizationAffiliation, PackagedProductDefinition, Patient, PaymentNotice, PaymentReconciliation, Person, PlanDefinition, Practitioner, PractitionerRole, Procedure, Questionnaire, QuestionnaireResponse, RegulatedAuthorization, RelatedPerson, RequestOrchestration, Requirements, ResearchStudy, ResearchSubject, RiskAssessment, Schedule, SearchParameter, ServiceRequest, Slot, Specimen, SpecimenDefinition, StructureDefinition, StructureMap, Subscription, SubscriptionTopic, Substance, SubstanceDefinition, SubstanceNucleicAcid, SubstancePolymer, SubstanceProtein, SubstanceReferenceInformation, SubstanceSourceMaterial, SupplyDelivery, SupplyRequest, Task, TerminologyCapabilities, TestPlan, TestReport, TestScript, Transport, ValueSet and VisionPrescription

FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Normative

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 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.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. HumanNameΣNElementName of a human or other living entity - parts and usage

Elements defined in Ancestors: id, extension
... use?!Σ0..1codeusual | official | temp | nickname | anonymous | old | maiden
Binding: NameUse (Required)
... textΣ0..1stringText representation of the full name
... familyΣ0..1stringFamily name (often called 'Surname')
... prefixΣ0..*stringParts that come before the name
This repeating element order: Prefixes appear in the correct order for presenting the name
... suffixΣ0..*stringParts that come after the name
This repeating element order: Suffixes appear in the correct order for presenting the name
... periodΣ0..1PeriodTime period when name was/is in use

doco Documentation for this format icon

Definition: XML | JSON

XML Template

<HumanName xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <use value="[code]"/><!-- 0..1 usual | official | temp | nickname | anonymous | old | maiden -->
 <text value="[string]"/><!-- 0..1 Text representation of the full name -->
 <family value="[string]"/><!-- 0..1 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>
</HumanName>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:use [ code ] ; # 0..1 usual | official | temp | nickname | anonymous | old | maiden
  fhir:text [ string ] ; # 0..1 Text representation of the full name
  fhir:family [ string ] ; # 0..1 Family name (often called 'Surname')
  fhir:given  ( [ string ] ... ) ; # 0..* Given names (not always 'first'). Includes middle names
  fhir:prefix  ( [ string ] ... ) ; # 0..* Parts that come before the name
  fhir:suffix  ( [ string ] ... ) ; # 0..* Parts that come after the name
  fhir:period [ Period ] ; # 0..1 Time period when name was/is in use
]

Changes since Release 3

Changes from both R4 and R4B

HumanName
  • No Changes

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. HumanNameΣNElementName of a human or other living entity - parts and usage

Elements defined in Ancestors: id, extension
... use?!Σ0..1codeusual | official | temp | nickname | anonymous | old | maiden
Binding: NameUse (Required)
... textΣ0..1stringText representation of the full name
... familyΣ0..1stringFamily name (often called 'Surname')
... prefixΣ0..*stringParts that come before the name
This repeating element order: Prefixes appear in the correct order for presenting the name
... suffixΣ0..*stringParts that come after the name
This repeating element order: Suffixes appear in the correct order for presenting the name
... periodΣ0..1PeriodTime period when name was/is in use

doco Documentation for this format icon

XML Template

<HumanName xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <use value="[code]"/><!-- 0..1 usual | official | temp | nickname | anonymous | old | maiden -->
 <text value="[string]"/><!-- 0..1 Text representation of the full name -->
 <family value="[string]"/><!-- 0..1 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>
</HumanName>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:use [ code ] ; # 0..1 usual | official | temp | nickname | anonymous | old | maiden
  fhir:text [ string ] ; # 0..1 Text representation of the full name
  fhir:family [ string ] ; # 0..1 Family name (often called 'Surname')
  fhir:given  ( [ string ] ... ) ; # 0..* Given names (not always 'first'). Includes middle names
  fhir:prefix  ( [ string ] ... ) ; # 0..* Parts that come before the name
  fhir:suffix  ( [ string ] ... ) ; # 0..* Parts that come after the name
  fhir:period [ Period ] ; # 0..1 Time period when name was/is in use
]

Changes since Release 3

Changes from both R4 and R4B

HumanName
  • No Changes

See the Full Difference for further information

This table summarizes where common parts of a person's name are found.

NameExampleDestination / Comments
SurnameSmithFamily Name
First nameJohnGiven Name
TitleMr.Prefix
Middle NameSamuelSubsequent Given Names
Patronymicbin OsmanFamily Name
Multiple family namesCarreño QuiñonesFamily Name. See note below about decomposition of family name
InitialsQ.Given Name as initial ("." recommended)
Nick NameJockGiven name, with Use = nickname
QualificationsPhDSuffix
HonorificsSeniorSuffix
Voorvoegsel / Nobilityvan BeethovenFamily Name. See note below about decomposition of family name

For further information, including all W3C International Examples icon, 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

Terminology Bindings

PathValueSetTypeDocumentation
HumanName.use NameUse Required

The use of a human name.

HumanName is used in the following places: ExtendedContactDetail, Patient, Person, Practitioner and RelatedPerson

FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Normative

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 Conversions

An address expressed using postal conventions (as opposed to GPS or other location definition formats). This datatype 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.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. AddressΣNElementAn address expressed using postal conventions (as opposed to GPS or other location definition formats)

Elements defined in Ancestors: id, extension
... use?!Σ0..1codehome | work | temp | old | billing - purpose of this address
Binding: AddressUse (Required)
... typeΣ0..1codepostal | physical | both
Binding: AddressType (Required)
... textΣ0..1stringText representation of the address
... cityΣ0..1stringName of city, town etc.
... districtΣ0..1stringDistrict name (aka county)
... stateΣ0..1stringSub-unit of country (abbreviations ok)
... postalCodeΣ0..1stringPostal code for area
... countryΣ0..1stringCountry (e.g. may be ISO 3166 2 or 3 letter code)
... periodΣ0..1PeriodTime period when address was/is in use

doco Documentation for this format icon

Definition: XML | JSON

XML Template

<Address xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <use value="[code]"/><!-- 0..1 home | work | temp | old | billing - purpose of this address -->
 <type value="[code]"/><!-- 0..1 postal | physical | both -->
 <text value="[string]"/><!-- 0..1 Text representation of the address -->
 <line value="[string]"/><!-- 0..* Street name, number, direction & P.O. Box etc. -->
 <city value="[string]"/><!-- 0..1 Name of city, town etc. -->
 <district value="[string]"/><!-- 0..1 District name (aka county) -->
 <state value="[string]"/><!-- 0..1 Sub-unit of country (abbreviations ok) -->
 <postalCode value="[string]"/><!-- 0..1 Postal code for area -->
 <country value="[string]"/><!-- 0..1 Country (e.g. may be ISO 3166 2 or 3 letter code) -->
 <period><!-- 0..1 Period Time period when address was/is in use --></period>
</Address>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:use [ code ] ; # 0..1 home | work | temp | old | billing - purpose of this address
  fhir:type [ code ] ; # 0..1 postal | physical | both
  fhir:text [ string ] ; # 0..1 Text representation of the address
  fhir:line  ( [ string ] ... ) ; # 0..* Street name, number, direction & P.O. Box etc.
  fhir:city [ string ] ; # 0..1 Name of city, town etc.
  fhir:district [ string ] ; # 0..1 District name (aka county)
  fhir:state [ string ] ; # 0..1 Sub-unit of country (abbreviations ok)
  fhir:postalCode [ string ] ; # 0..1 Postal code for area
  fhir:country [ string ] ; # 0..1 Country (e.g. may be ISO 3166 2 or 3 letter code)
  fhir:period [ Period ] ; # 0..1 Time period when address was/is in use
]

Changes since Release 3

Changes from both R4 and R4B

Address
  • No Changes

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. AddressΣNElementAn address expressed using postal conventions (as opposed to GPS or other location definition formats)

Elements defined in Ancestors: id, extension
... use?!Σ0..1codehome | work | temp | old | billing - purpose of this address
Binding: AddressUse (Required)
... typeΣ0..1codepostal | physical | both
Binding: AddressType (Required)
... textΣ0..1stringText representation of the address
... cityΣ0..1stringName of city, town etc.
... districtΣ0..1stringDistrict name (aka county)
... stateΣ0..1stringSub-unit of country (abbreviations ok)
... postalCodeΣ0..1stringPostal code for area
... countryΣ0..1stringCountry (e.g. may be ISO 3166 2 or 3 letter code)
... periodΣ0..1PeriodTime period when address was/is in use

doco Documentation for this format icon

XML Template

<Address xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <use value="[code]"/><!-- 0..1 home | work | temp | old | billing - purpose of this address -->
 <type value="[code]"/><!-- 0..1 postal | physical | both -->
 <text value="[string]"/><!-- 0..1 Text representation of the address -->
 <line value="[string]"/><!-- 0..* Street name, number, direction & P.O. Box etc. -->
 <city value="[string]"/><!-- 0..1 Name of city, town etc. -->
 <district value="[string]"/><!-- 0..1 District name (aka county) -->
 <state value="[string]"/><!-- 0..1 Sub-unit of country (abbreviations ok) -->
 <postalCode value="[string]"/><!-- 0..1 Postal code for area -->
 <country value="[string]"/><!-- 0..1 Country (e.g. may be ISO 3166 2 or 3 letter code) -->
 <period><!-- 0..1 Period Time period when address was/is in use --></period>
</Address>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:use [ code ] ; # 0..1 home | work | temp | old | billing - purpose of this address
  fhir:type [ code ] ; # 0..1 postal | physical | both
  fhir:text [ string ] ; # 0..1 Text representation of the address
  fhir:line  ( [ string ] ... ) ; # 0..* Street name, number, direction & P.O. Box etc.
  fhir:city [ string ] ; # 0..1 Name of city, town etc.
  fhir:district [ string ] ; # 0..1 District name (aka county)
  fhir:state [ string ] ; # 0..1 Sub-unit of country (abbreviations ok)
  fhir:postalCode [ string ] ; # 0..1 Postal code for area
  fhir:country [ string ] ; # 0..1 Country (e.g. may be ISO 3166 2 or 3 letter code)
  fhir:period [ Period ] ; # 0..1 Time period when address was/is in use
]

Changes since Release 3

Changes from both R4 and R4B

Address
  • No Changes

See the Full Difference for further information

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

Terminology Bindings

PathValueSetTypeDocumentation
Address.use AddressUse Required

The use of an address.

Address.type AddressType Required

The type of an address (physical / postal).

Address is used in the following places: ExtendedContactDetail, Claim, ClaimResponse, ExplanationOfBenefit, InventoryItem, Location, Patient, Person, Practitioner and RelatedPerson

FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Normative

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 Conversions

Details for all kinds of technology-mediated contact points for a person or organization, including telephone, email, etc.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. ContactPointΣNElementDetails of a Technology mediated contact point (phone, fax, email, etc.)
+ Rule: A system is required if a value is provided.

Elements defined in Ancestors: id, extension
... systemΣC0..1codephone | fax | email | pager | url | sms | other
Binding: ContactPointSystem (Required)
... valueΣC0..1stringThe actual contact point details
... use?!Σ0..1codehome | work | temp | old | mobile - purpose of this contact point
Binding: ContactPointUse (Required)
... periodΣ0..1PeriodTime period when the contact point was/is in use

doco Documentation for this format icon

Definition: XML | JSON

XML Template

<ContactPoint xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <system value="[code]"/><!-- I 0..1 phone | fax | email | pager | url | sms | other -->
 <value value="[string]"/><!-- I 0..1 The actual contact point details -->
 <use value="[code]"/><!-- 0..1 home | work | temp | old | mobile - purpose of this contact point -->
 <rank value="[positiveInt]"/><!-- 0..1 Specify preferred order of use (1 = highest) -->
 <period><!-- 0..1 Period Time period when the contact point was/is in use --></period>
</ContactPoint>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:system [ code ] ; # 0..1 I phone | fax | email | pager | url | sms | other
  fhir:value [ string ] ; # 0..1 I The actual contact point details
  fhir:use [ code ] ; # 0..1 home | work | temp | old | mobile - purpose of this contact point
  fhir:rank [ positiveInt ] ; # 0..1 Specify preferred order of use (1 = highest)
  fhir:period [ Period ] ; # 0..1 Time period when the contact point was/is in use
]

Changes since Release 3

Changes from both R4 and R4B

ContactPoint
  • No Changes

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. ContactPointΣNElementDetails of a Technology mediated contact point (phone, fax, email, etc.)
+ Rule: A system is required if a value is provided.

Elements defined in Ancestors: id, extension
... systemΣC0..1codephone | fax | email | pager | url | sms | other
Binding: ContactPointSystem (Required)
... valueΣC0..1stringThe actual contact point details
... use?!Σ0..1codehome | work | temp | old | mobile - purpose of this contact point
Binding: ContactPointUse (Required)
... periodΣ0..1PeriodTime period when the contact point was/is in use

doco Documentation for this format icon

XML Template

<ContactPoint xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <system value="[code]"/><!-- I 0..1 phone | fax | email | pager | url | sms | other -->
 <value value="[string]"/><!-- I 0..1 The actual contact point details -->
 <use value="[code]"/><!-- 0..1 home | work | temp | old | mobile - purpose of this contact point -->
 <rank value="[positiveInt]"/><!-- 0..1 Specify preferred order of use (1 = highest) -->
 <period><!-- 0..1 Period Time period when the contact point was/is in use --></period>
</ContactPoint>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:system [ code ] ; # 0..1 I phone | fax | email | pager | url | sms | other
  fhir:value [ string ] ; # 0..1 I The actual contact point details
  fhir:use [ code ] ; # 0..1 home | work | temp | old | mobile - purpose of this contact point
  fhir:rank [ positiveInt ] ; # 0..1 Specify preferred order of use (1 = highest)
  fhir:period [ Period ] ; # 0..1 Time period when the contact point was/is in use
]

Changes since Release 3

Changes from both R4 and R4B

ContactPoint
  • No Changes

See the Full Difference for further information

If capturing a phone, fax or similar contact point, the value should be a properly formatted telephone number according to ITU-T E.123 icon. 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.

Constraints

idLevelLocationDescriptionExpression
img cpt-2Rule (base)A system is required if a value is provided.value.empty() or system.exists()

Terminology Bindings

PathValueSetTypeDocumentation
ContactPoint.system ContactPointSystem Required

Telecommunications form for contact point.

ContactPoint.use ContactPointUse Required

Use of contact point.

ContactPoint is used in the following places: VirtualServiceDetail, ContactDetail, ExtendedContactDetail, CareTeam, Device, DeviceDefinition, Endpoint, MessageHeader, Patient, Person, Practitioner, RelatedPerson and Subscription

FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Normative

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 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 datatype allows modifier extensions.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. TimingΣNElementA timing schedule that specifies an event that may occur multiple times

Elements defined in Ancestors: id, extension, modifierExtension
... eventΣ0..*dateTimeWhen the event occurs

... repeatΣC0..1ElementWhen the event is to occur
+ Rule: if there's a duration, there needs to be duration units
+ Rule: if there's a period, there needs to be period units
+ Rule: duration SHALL be a non-negative value
+ Rule: period SHALL be a non-negative value
+ Rule: If there's a periodMax, there must be a period
+ Rule: If there's a durationMax, there must be a duration
+ Rule: If there's a countMax, there must be a count
+ Rule: If there's an offset, there must be a when (and not C, CM, CD, CV)
+ Rule: If there's a timeOfDay, there cannot be a when, or vice versa
.... bounds[x]Σ0..1Length/Range of lengths, or (Start and/or end) limits
..... boundsDurationDuration
..... boundsRangeRange
..... boundsPeriodPeriod
.... countΣC0..1positiveIntNumber of times to repeat
.... countMaxΣC0..1positiveIntMaximum number of times to repeat
.... durationΣC0..1decimalHow long when it happens
.... durationMaxΣC0..1decimalHow long when it happens (Max)
.... durationUnitΣC0..1codes | min | h | d | wk | mo | a - unit of time (UCUM)
Binding: UnitsOfTime (Required)
.... frequencyΣ0..1positiveIntIndicates the number of repetitions that should occur within a period. I.e. Event occurs frequency times per period
.... frequencyMaxΣ0..1positiveIntEvent occurs up to frequencyMax times per period
.... periodΣC0..1decimalThe duration to which the frequency applies. I.e. Event occurs frequency times per period
.... periodMaxΣC0..1decimalUpper limit of period (3-4 hours)
.... periodUnitΣC0..1codes | min | h | d | wk | mo | a - unit of time (UCUM)
Binding: UnitsOfTime (Required)
.... dayOfWeekΣ0..*codemon | tue | wed | thu | fri | sat | sun
Binding: Days Of Week (Required)

.... timeOfDayΣC0..*timeTime of day for action

.... whenΣC0..*codeCode for time period of occurrence
Binding: EventTiming (Required)

.... offsetΣC0..1unsignedIntMinutes from event (before or after)
... codeΣ0..1CodeableConceptC | BID | TID | QID | AM | PM | QD | QOD | +
Binding: TimingAbbreviation (Preferred)

doco Documentation for this format icon

Definition: XML | JSON

UML Diagram (Legend)

TimingIdentifies specific times when the event occursevent : dateTime [0..*]A code for the timing schedule (or just text in code.text). Some codes such as BID are ubiquitous, but many institutions define their own additional codes. If a code is provided, the code is understood to be a complete statement of whatever is specified in the structured timing data, and either the code or the data may be used to interpret the Timing, with the exception that .repeat.bounds still applies over the code (and is not contained in the code)code : CodeableConcept [0..1] « Code for a known / defined timing pattern. (Strength=Preferred)TimingAbbreviation? »RepeatEither a duration for the length of the timing schedule, a range of possible length, or outer bounds for start and/or end limits of the timing schedulebounds[x] : DataType [0..1] « Duration|Range|Period »A total count of the desired number of repetitions across the duration of the entire timing specification. If countMax is present, this element indicates the lower bound of the allowed range of count valuescount : positiveInt [0..1] « This element has or is affected by some invariantsC »If present, indicates that the count is a range - so to perform the action between [count] and [countMax] timescountMax : positiveInt [0..1] « This element has or is affected by some invariantsC »How long this thing happens for when it happens. If durationMax is present, this element indicates the lower bound of the allowed range of the durationduration : decimal [0..1] « This element has or is affected by some invariantsC »If present, indicates that the duration is a range - so to perform the action between [duration] and [durationMax] time lengthdurationMax : decimal [0..1] « This element has or is affected by some invariantsC »The units of time for the duration, in UCUM units Normal practice is to use the 'mo' code as a calendar month when calculating the next occurrencedurationUnit : code [0..1] « A unit of time (units from UCUM). (Strength=Required)UnitsOfTime! » « This element has or is affected by some invariantsC »The number of times to repeat the action within the specified period. If frequencyMax is present, this element indicates the lower bound of the allowed range of the frequencyfrequency : positiveInt [0..1]If present, indicates that the frequency is a range - so to repeat between [frequency] and [frequencyMax] times within the period or period rangefrequencyMax : positiveInt [0..1]Indicates the duration of time over which repetitions are to occur; e.g. to express "3 times per day", 3 would be the frequency and "1 day" would be the period. If periodMax is present, this element indicates the lower bound of the allowed range of the period lengthperiod : decimal [0..1] « This element has or is affected by some invariantsC »If present, indicates that the period is a range from [period] to [periodMax], allowing expressing concepts such as "do this once every 3-5 daysperiodMax : decimal [0..1] « This element has or is affected by some invariantsC »The units of time for the period in UCUM units Normal practice is to use the 'mo' code as a calendar month when calculating the next occurrenceperiodUnit : code [0..1] « A unit of time (units from UCUM). (Strength=Required)UnitsOfTime! » « This element has or is affected by some invariantsC »If one or more days of week is provided, then the action happens only on the specified day(s)dayOfWeek : code [0..*] « (Strength=Required)DaysOfWeek! »Specified time of day for action to take placetimeOfDay : time [0..*] « This element has or is affected by some invariantsC »An approximate time period during the day, potentially linked to an event of daily living that indicates when the action should occurwhen : code [0..*] « Real-world event relating to the schedule. (Strength=Required)EventTiming! » « This element has or is affected by some invariantsC »The number of minutes from the event. If the event code does not indicate whether the minutes is before or after the event, then the offset is assumed to be after the eventoffset : unsignedInt [0..1] « This element has or is affected by some invariantsC »BackboneTypeMay be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and managable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself) (this element modifies the meaning of other elements)modifierExtension : Extension [0..*]A set of rules that describe when the event is scheduledrepeat[0..1]

XML Template

<Timing xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <event value="[dateTime]"/><!-- 0..* When the event occurs -->
 <repeat>  <!-- 0..1 When the event is to occur -->
  <bounds[x]><!-- 0..1 Duration|Range|Period Length/Range of lengths, or (Start and/or end) limits --></bounds[x]>
  <count value="[positiveInt]"/><!-- I 0..1 Number of times to repeat -->
  <countMax value="[positiveInt]"/><!-- I 0..1 Maximum number of times to repeat -->
  <duration value="[decimal]"/><!-- I 0..1 How long when it happens -->
  <durationMax value="[decimal]"/><!-- I 0..1 How long when it happens (Max) -->
  <durationUnit value="[code]"/><!-- I 0..1 s | min | h | d | wk | mo | a - unit of time (UCUM) -->
  <frequency value="[positiveInt]"/><!-- 0..1 Indicates the number of repetitions that should occur within a period. I.e. Event occurs frequency times per period -->
  <frequencyMax value="[positiveInt]"/><!-- 0..1 Event occurs up to frequencyMax times per period -->
  <period value="[decimal]"/><!-- I 0..1 The duration to which the frequency applies. I.e. Event occurs frequency times per period -->
  <periodMax value="[decimal]"/><!-- I 0..1 Upper limit of period (3-4 hours) -->
  <periodUnit value="[code]"/><!-- I 0..1 s | min | h | d | wk | mo | a - unit of time (UCUM) -->
  <dayOfWeek value="[code]"/><!-- 0..* mon | tue | wed | thu | fri | sat | sun -->
  <timeOfDay value="[time]"/><!-- I 0..* Time of day for action -->
  <when value="[code]"/><!-- I 0..* Code for time period of occurrence -->
  <offset value="[unsignedInt]"/><!-- I 0..1 Minutes from event (before or after) -->
 </repeat>
 <code><!-- 0..1 CodeableConcept C | BID | TID | QID | AM | PM | QD | QOD | + --></code>
</Timing>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:event  ( [ dateTime ] ... ) ; # 0..* When the event occurs
  fhir:repeat [ # 0..1 When the event is to occur
    # bounds[x] : 0..1 Length/Range of lengths, or (Start and/or end) limits. One of these 3
      fhir:bounds [  a fhir:Duration ; Duration ]
      fhir:bounds [  a fhir:Range ; Range ]
      fhir:bounds [  a fhir:Period ; Period ]
    fhir:count [ positiveInt ] ; # 0..1 I Number of times to repeat
    fhir:countMax [ positiveInt ] ; # 0..1 I Maximum number of times to repeat
    fhir:duration [ decimal ] ; # 0..1 I How long when it happens
    fhir:durationMax [ decimal ] ; # 0..1 I How long when it happens (Max)
    fhir:durationUnit [ code ] ; # 0..1 I s | min | h | d | wk | mo | a - unit of time (UCUM)
    fhir:frequency [ positiveInt ] ; # 0..1 Indicates the number of repetitions that should occur within a period. I.e. Event occurs frequency times per period
    fhir:frequencyMax [ positiveInt ] ; # 0..1 Event occurs up to frequencyMax times per period
    fhir:period [ decimal ] ; # 0..1 I The duration to which the frequency applies. I.e. Event occurs frequency times per period
    fhir:periodMax [ decimal ] ; # 0..1 I Upper limit of period (3-4 hours)
    fhir:periodUnit [ code ] ; # 0..1 I s | min | h | d | wk | mo | a - unit of time (UCUM)
    fhir:dayOfWeek  ( [ code ] ... ) ; # 0..* mon | tue | wed | thu | fri | sat | sun
    fhir:timeOfDay  ( [ time ] ... ) ; # 0..* I Time of day for action
    fhir:when  ( [ code ] ... ) ; # 0..* I Code for time period of occurrence
    fhir:offset [ unsignedInt ] ; # 0..1 I Minutes from event (before or after)
  ] ;
  fhir:code [ CodeableConcept ] ; # 0..1 C | BID | TID | QID | AM | PM | QD | QOD | +
]

Changes since Release 3

Changes from both R4 and R4B

Timing
Timing.repeat.when
  • Add code IMD

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. TimingΣNElementA timing schedule that specifies an event that may occur multiple times

Elements defined in Ancestors: id, extension, modifierExtension
... eventΣ0..*dateTimeWhen the event occurs

... repeatΣC0..1ElementWhen the event is to occur
+ Rule: if there's a duration, there needs to be duration units
+ Rule: if there's a period, there needs to be period units
+ Rule: duration SHALL be a non-negative value
+ Rule: period SHALL be a non-negative value
+ Rule: If there's a periodMax, there must be a period
+ Rule: If there's a durationMax, there must be a duration
+ Rule: If there's a countMax, there must be a count
+ Rule: If there's an offset, there must be a when (and not C, CM, CD, CV)
+ Rule: If there's a timeOfDay, there cannot be a when, or vice versa
.... bounds[x]Σ0..1Length/Range of lengths, or (Start and/or end) limits
..... boundsDurationDuration
..... boundsRangeRange
..... boundsPeriodPeriod
.... countΣC0..1positiveIntNumber of times to repeat
.... countMaxΣC0..1positiveIntMaximum number of times to repeat
.... durationΣC0..1decimalHow long when it happens
.... durationMaxΣC0..1decimalHow long when it happens (Max)
.... durationUnitΣC0..1codes | min | h | d | wk | mo | a - unit of time (UCUM)
Binding: UnitsOfTime (Required)
.... frequencyΣ0..1positiveIntIndicates the number of repetitions that should occur within a period. I.e. Event occurs frequency times per period
.... frequencyMaxΣ0..1positiveIntEvent occurs up to frequencyMax times per period
.... periodΣC0..1decimalThe duration to which the frequency applies. I.e. Event occurs frequency times per period
.... periodMaxΣC0..1decimalUpper limit of period (3-4 hours)
.... periodUnitΣC0..1codes | min | h | d | wk | mo | a - unit of time (UCUM)
Binding: UnitsOfTime (Required)
.... dayOfWeekΣ0..*codemon | tue | wed | thu | fri | sat | sun
Binding: Days Of Week (Required)

.... timeOfDayΣC0..*timeTime of day for action

.... whenΣC0..*codeCode for time period of occurrence
Binding: EventTiming (Required)

.... offsetΣC0..1unsignedIntMinutes from event (before or after)
... codeΣ0..1CodeableConceptC | BID | TID | QID | AM | PM | QD | QOD | +
Binding: TimingAbbreviation (Preferred)

doco Documentation for this format icon

UML Diagram (Legend)

TimingIdentifies specific times when the event occursevent : dateTime [0..*]A code for the timing schedule (or just text in code.text). Some codes such as BID are ubiquitous, but many institutions define their own additional codes. If a code is provided, the code is understood to be a complete statement of whatever is specified in the structured timing data, and either the code or the data may be used to interpret the Timing, with the exception that .repeat.bounds still applies over the code (and is not contained in the code)code : CodeableConcept [0..1] « Code for a known / defined timing pattern. (Strength=Preferred)TimingAbbreviation? »RepeatEither a duration for the length of the timing schedule, a range of possible length, or outer bounds for start and/or end limits of the timing schedulebounds[x] : DataType [0..1] « Duration|Range|Period »A total count of the desired number of repetitions across the duration of the entire timing specification. If countMax is present, this element indicates the lower bound of the allowed range of count valuescount : positiveInt [0..1] « This element has or is affected by some invariantsC »If present, indicates that the count is a range - so to perform the action between [count] and [countMax] timescountMax : positiveInt [0..1] « This element has or is affected by some invariantsC »How long this thing happens for when it happens. If durationMax is present, this element indicates the lower bound of the allowed range of the durationduration : decimal [0..1] « This element has or is affected by some invariantsC »If present, indicates that the duration is a range - so to perform the action between [duration] and [durationMax] time lengthdurationMax : decimal [0..1] « This element has or is affected by some invariantsC »The units of time for the duration, in UCUM units Normal practice is to use the 'mo' code as a calendar month when calculating the next occurrencedurationUnit : code [0..1] « A unit of time (units from UCUM). (Strength=Required)UnitsOfTime! » « This element has or is affected by some invariantsC »The number of times to repeat the action within the specified period. If frequencyMax is present, this element indicates the lower bound of the allowed range of the frequencyfrequency : positiveInt [0..1]If present, indicates that the frequency is a range - so to repeat between [frequency] and [frequencyMax] times within the period or period rangefrequencyMax : positiveInt [0..1]Indicates the duration of time over which repetitions are to occur; e.g. to express "3 times per day", 3 would be the frequency and "1 day" would be the period. If periodMax is present, this element indicates the lower bound of the allowed range of the period lengthperiod : decimal [0..1] « This element has or is affected by some invariantsC »If present, indicates that the period is a range from [period] to [periodMax], allowing expressing concepts such as "do this once every 3-5 daysperiodMax : decimal [0..1] « This element has or is affected by some invariantsC »The units of time for the period in UCUM units Normal practice is to use the 'mo' code as a calendar month when calculating the next occurrenceperiodUnit : code [0..1] « A unit of time (units from UCUM). (Strength=Required)UnitsOfTime! » « This element has or is affected by some invariantsC »If one or more days of week is provided, then the action happens only on the specified day(s)dayOfWeek : code [0..*] « (Strength=Required)DaysOfWeek! »Specified time of day for action to take placetimeOfDay : time [0..*] « This element has or is affected by some invariantsC »An approximate time period during the day, potentially linked to an event of daily living that indicates when the action should occurwhen : code [0..*] « Real-world event relating to the schedule. (Strength=Required)EventTiming! » « This element has or is affected by some invariantsC »The number of minutes from the event. If the event code does not indicate whether the minutes is before or after the event, then the offset is assumed to be after the eventoffset : unsignedInt [0..1] « This element has or is affected by some invariantsC »BackboneTypeMay be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and managable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself) (this element modifies the meaning of other elements)modifierExtension : Extension [0..*]A set of rules that describe when the event is scheduledrepeat[0..1]

XML Template

<Timing xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <event value="[dateTime]"/><!-- 0..* When the event occurs -->
 <repeat>  <!-- 0..1 When the event is to occur -->
  <bounds[x]><!-- 0..1 Duration|Range|Period Length/Range of lengths, or (Start and/or end) limits --></bounds[x]>
  <count value="[positiveInt]"/><!-- I 0..1 Number of times to repeat -->
  <countMax value="[positiveInt]"/><!-- I 0..1 Maximum number of times to repeat -->
  <duration value="[decimal]"/><!-- I 0..1 How long when it happens -->
  <durationMax value="[decimal]"/><!-- I 0..1 How long when it happens (Max) -->
  <durationUnit value="[code]"/><!-- I 0..1 s | min | h | d | wk | mo | a - unit of time (UCUM) -->
  <frequency value="[positiveInt]"/><!-- 0..1 Indicates the number of repetitions that should occur within a period. I.e. Event occurs frequency times per period -->
  <frequencyMax value="[positiveInt]"/><!-- 0..1 Event occurs up to frequencyMax times per period -->
  <period value="[decimal]"/><!-- I 0..1 The duration to which the frequency applies. I.e. Event occurs frequency times per period -->
  <periodMax value="[decimal]"/><!-- I 0..1 Upper limit of period (3-4 hours) -->
  <periodUnit value="[code]"/><!-- I 0..1 s | min | h | d | wk | mo | a - unit of time (UCUM) -->
  <dayOfWeek value="[code]"/><!-- 0..* mon | tue | wed | thu | fri | sat | sun -->
  <timeOfDay value="[time]"/><!-- I 0..* Time of day for action -->
  <when value="[code]"/><!-- I 0..* Code for time period of occurrence -->
  <offset value="[unsignedInt]"/><!-- I 0..1 Minutes from event (before or after) -->
 </repeat>
 <code><!-- 0..1 CodeableConcept C | BID | TID | QID | AM | PM | QD | QOD | + --></code>
</Timing>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:event  ( [ dateTime ] ... ) ; # 0..* When the event occurs
  fhir:repeat [ # 0..1 When the event is to occur
    # bounds[x] : 0..1 Length/Range of lengths, or (Start and/or end) limits. One of these 3
      fhir:bounds [  a fhir:Duration ; Duration ]
      fhir:bounds [  a fhir:Range ; Range ]
      fhir:bounds [  a fhir:Period ; Period ]
    fhir:count [ positiveInt ] ; # 0..1 I Number of times to repeat
    fhir:countMax [ positiveInt ] ; # 0..1 I Maximum number of times to repeat
    fhir:duration [ decimal ] ; # 0..1 I How long when it happens
    fhir:durationMax [ decimal ] ; # 0..1 I How long when it happens (Max)
    fhir:durationUnit [ code ] ; # 0..1 I s | min | h | d | wk | mo | a - unit of time (UCUM)
    fhir:frequency [ positiveInt ] ; # 0..1 Indicates the number of repetitions that should occur within a period. I.e. Event occurs frequency times per period
    fhir:frequencyMax [ positiveInt ] ; # 0..1 Event occurs up to frequencyMax times per period
    fhir:period [ decimal ] ; # 0..1 I The duration to which the frequency applies. I.e. Event occurs frequency times per period
    fhir:periodMax [ decimal ] ; # 0..1 I Upper limit of period (3-4 hours)
    fhir:periodUnit [ code ] ; # 0..1 I s | min | h | d | wk | mo | a - unit of time (UCUM)
    fhir:dayOfWeek  ( [ code ] ... ) ; # 0..* mon | tue | wed | thu | fri | sat | sun
    fhir:timeOfDay  ( [ time ] ... ) ; # 0..* I Time of day for action
    fhir:when  ( [ code ] ... ) ; # 0..* I Code for time period of occurrence
    fhir:offset [ unsignedInt ] ; # 0..1 I Minutes from event (before or after)
  ] ;
  fhir:code [ CodeableConcept ] ; # 0..1 C | BID | TID | QID | AM | PM | QD | QOD | +
]

Changes since Release 3

Changes from both R4 and R4B

Timing
Timing.repeat.when
  • Add code IMD

See the Full Difference for further information

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.

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 datatype. 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 summarizes some common uses of the Timing Datatype 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

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

idLevelLocationDescriptionExpression
img tim-1Rule Timing.repeatif there's a duration, there needs to be duration unitsduration.empty() or durationUnit.exists()
img tim-2Rule Timing.repeatif there's a period, there needs to be period unitsperiod.empty() or periodUnit.exists()
img tim-4Rule Timing.repeatduration SHALL be a non-negative valueduration.exists() implies duration >= 0
img tim-5Rule Timing.repeatperiod SHALL be a non-negative valueperiod.exists() implies period >= 0
img tim-6Rule Timing.repeatIf there's a periodMax, there must be a periodperiodMax.empty() or period.exists()
img tim-7Rule Timing.repeatIf there's a durationMax, there must be a durationdurationMax.empty() or duration.exists()
img tim-8Rule Timing.repeatIf there's a countMax, there must be a countcountMax.empty() or count.exists()
img tim-9Rule Timing.repeatIf there's an offset, there must be a when (and not C, CM, CD, CV)offset.empty() or (when.exists() and when.select($this in ('C' | 'CM' | 'CD' | 'CV')).allFalse())
img tim-10Rule Timing.repeatIf there's a timeOfDay, there cannot be a when, or vice versatimeOfDay.empty() or when.empty()

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.

Terminology Bindings

PathValueSetTypeDocumentation
Timing.repeat.durationUnit
Timing.repeat.periodUnit
UnitsOfTime Required

A unit of time (units from UCUM).

Timing.repeat.dayOfWeek DaysOfWeek Required

The days of the week.

Timing.repeat.when EventTiming Required

Real-world event relating to the schedule.

Timing.code TimingAbbreviation Preferred

Code for a known / defined timing pattern.

Timing is used in the following places: Dosage, TriggerDefinition, ActivityDefinition, CareTeam, ChargeItem, Contract, DeviceRequest, DeviceUsage, MedicationAdministration, MedicationStatement, NutritionIntake, NutritionOrder, Observation, PlanDefinition, Procedure, RequestOrchestration, ServiceRequest, SupplyDelivery, SupplyRequest and VerificationResult

FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Trial Use

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 Conversions

RelativeTime is used to express a point in time or an interval of time relative to an event defined in data types other than dateTime. For example, "within 30 days of hospital discharge" is an interval of time (from 0 days to 30 days) and it is described as occurring after an event (hospital discharge).

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. RelativeTimeΣTUElementA point in time or an interval of time relative to an event
+ Rule: A RelativeTime can have either a contextReference or contextDefinition but not both
+ Rule: If RelativeTime has a contextPath, it SHALL have either a contextReference or a contextDefinition

Elements defined in Ancestors: id, extension, modifierExtension
... contextReferenceΣC0..1Reference(Any)The specific event occurrence or resource context used as a base point (reference point) in time
... contextDefinitionΣC0..1canonical(ActivityDefinition | PlanDefinition | ObservationDefinition)The type of event used as a base point
... contextPathΣC0..1stringPath to the element defining the point in time
... offset[x]Σ0..1An offset or offset range before (negative values) or after (positive values) the event
.... offsetDurationDuration
.... offsetRangeRange
... textΣ0..1stringFree-text description

doco Documentation for this format icon

Definition: XML | JSON

UML Diagram (Legend)

RelativeTimeThe specific event occurrence or resource context used as a base point (reference point) in time. This establishes the context in which the 'path' is evaluatedcontextReference : Reference [0..1] « Any » « This element has or is affected by some invariantsC »The type of event used as a base point. Instances of this definition will establish the context for evaluating the path to determine the base time for the offsetcontextDefinition : canonical [0..1] « ActivityDefinition| PlanDefinition|ObservationDefinition » « This element has or is affected by some invariantsC »Path to the element defining the point in time. Any valid FHIRPath expressioncontextPath : string [0..1] « This element has or is affected by some invariantsC »Coded representation of the event used as a base point (reference point) in timecontextCode : CodeableConcept [0..1] « The event used as a base point (reference point) in time. (Strength=Example)EvidenceVariableEvent?? »An offset or offset range before (negative values) or after (positive values) the event. Range is limited to time-valued quantities (Durations)offset[x] : DataType [0..1] « Duration|Range »Free-text (human-readable) descriptiontext : string [0..1]BackboneTypeMay be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and managable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself) (this element modifies the meaning of other elements)modifierExtension : Extension [0..*]

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:contextReference [ Reference(Any) ] ; # 0..1 I The specific event occurrence or resource context used as a base point (reference point) in time
  fhir:contextDefinition [ canonical(ActivityDefinition|ObservationDefinition|PlanDefinition) ] ; # 0..1 I The type of event used as a base point
  fhir:contextPath [ string ] ; # 0..1 I Path to the element defining the point in time
  fhir:contextCode [ CodeableConcept ] ; # 0..1 Coded representation of the event used as a base point (reference point) in time
  # offset[x] : 0..1 An offset or offset range before (negative values) or after (positive values) the event. One of these 2
    fhir:offset [  a fhir:Duration ; Duration ]
    fhir:offset [  a fhir:Range ; Range ]
  fhir:text [ string ] ; # 0..1 Free-text description
]

Changes since Release 3

Changes from both R4 and R4B

This complex-type did not exist in Release R4

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. RelativeTimeΣTUElementA point in time or an interval of time relative to an event
+ Rule: A RelativeTime can have either a contextReference or contextDefinition but not both
+ Rule: If RelativeTime has a contextPath, it SHALL have either a contextReference or a contextDefinition

Elements defined in Ancestors: id, extension, modifierExtension
... contextReferenceΣC0..1Reference(Any)The specific event occurrence or resource context used as a base point (reference point) in time
... contextDefinitionΣC0..1canonical(ActivityDefinition | PlanDefinition | ObservationDefinition)The type of event used as a base point
... contextPathΣC0..1stringPath to the element defining the point in time
... offset[x]Σ0..1An offset or offset range before (negative values) or after (positive values) the event
.... offsetDurationDuration
.... offsetRangeRange
... textΣ0..1stringFree-text description

doco Documentation for this format icon

UML Diagram (Legend)

RelativeTimeThe specific event occurrence or resource context used as a base point (reference point) in time. This establishes the context in which the 'path' is evaluatedcontextReference : Reference [0..1] « Any » « This element has or is affected by some invariantsC »The type of event used as a base point. Instances of this definition will establish the context for evaluating the path to determine the base time for the offsetcontextDefinition : canonical [0..1] « ActivityDefinition| PlanDefinition|ObservationDefinition » « This element has or is affected by some invariantsC »Path to the element defining the point in time. Any valid FHIRPath expressioncontextPath : string [0..1] « This element has or is affected by some invariantsC »Coded representation of the event used as a base point (reference point) in timecontextCode : CodeableConcept [0..1] « The event used as a base point (reference point) in time. (Strength=Example)EvidenceVariableEvent?? »An offset or offset range before (negative values) or after (positive values) the event. Range is limited to time-valued quantities (Durations)offset[x] : DataType [0..1] « Duration|Range »Free-text (human-readable) descriptiontext : string [0..1]BackboneTypeMay be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and managable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself) (this element modifies the meaning of other elements)modifierExtension : Extension [0..*]

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:contextReference [ Reference(Any) ] ; # 0..1 I The specific event occurrence or resource context used as a base point (reference point) in time
  fhir:contextDefinition [ canonical(ActivityDefinition|ObservationDefinition|PlanDefinition) ] ; # 0..1 I The type of event used as a base point
  fhir:contextPath [ string ] ; # 0..1 I Path to the element defining the point in time
  fhir:contextCode [ CodeableConcept ] ; # 0..1 Coded representation of the event used as a base point (reference point) in time
  # offset[x] : 0..1 An offset or offset range before (negative values) or after (positive values) the event. One of these 2
    fhir:offset [  a fhir:Duration ; Duration ]
    fhir:offset [  a fhir:Range ; Range ]
  fhir:text [ string ] ; # 0..1 Free-text description
]

Changes since Release 3

Changes from both R4 and R4B

This complex-type did not exist in Release R4

See the Full Difference for further information

Methods to express the "event" or "context" that is reference point for time relative to that point include any of:

  1. Describing the event fully with a CodeableConcept, in which case contextCode element is used.
  2. Describing the event with a reference to an applicable FHIR Resource for which the Resource defines or implies a moment in time, in which case contextReference element is used, or contextDefinition element may be used instead if the Resource is ActivityDefinition, PlanDefinition, or ObservationDefinition.
  3. Describing the event with a reference to an applicable FHIR Resource (using contextReference or contextDefinition) and additional data to express which element in the Resource defines or implies the moment in time, using either or both of contextPath (for the literal path to the element) or contextCode (for the CodeableConcept describing the property that is expected to be found in the Resource).

Methods to express the point in time or interval in time ("offset") relative to the "event" include any of:

  1. Describing an exact duration (quantity with a numerical value and time-specific unit), in which case offsetDuration is used.
  2. Describing a one-sided interval, in which case offsetDuration is used and includes offsetDuration.comparator with an appropriate code (>, >=, <, or <=).
  3. Describing a two-sided interval, in which case offsetRange is used, and the Quantity datatype within the low and high values are limited to Duration datatype (i.e. limited to time-specific units).
  4. Describing the exact moment of time (offset = 0), in which case offsetDuration.value = 0 and units are unnecessary.

The method to express a natural language description of the RelativeTime value is to use the text element.

FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Trial Use

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 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 digital-signature process.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. SignatureTUElementA Signature - XML DigSig, JWS, Graphical image of signature, etc.

Elements defined in Ancestors: id, extension
... typeΣ0..*CodingIndication of the reason the entity signed the object(s)
Binding: Signature Type Codes (Preferred)

... whenΣ0..1instantWhen the signature was created
... whoΣ0..1Reference(Practitioner | PractitionerRole | RelatedPerson | Patient | Device | Organization)Who signed
... targetFormat0..1codeThe technical format of the signed resources
Binding: Mime Types (Required)
... sigFormat0..1codeThe technical format of the signature
Binding: Mime Types (Required)
... data0..1base64BinaryThe actual signature content (XML DigSig. JWS, picture, etc.)

doco Documentation for this format icon

Definition: XML | JSON

UML Diagram (Legend)

SignatureAn indication of the reason that the entity signed this document. This may be explicitly included as part of the signature information and can be used when determining accountability for various actions concerning the documenttype : Coding [0..*] « An indication of the reason that an entity signed the object. (Strength=Preferred)SignatureTypeCodes? »When the digital signature was signedwhen : instant [0..1]A reference to an application-usable description of the identity that signed (e.g. the signature used their private key)who : Reference [0..1] « Practitioner|PractitionerRole|RelatedPerson| Patient|Device|Organization »A reference to an application-usable description of the identity that is represented by the signatureonBehalfOf : Reference [0..1] « Practitioner|PractitionerRole| RelatedPerson|Patient|Device|Organization »A mime type that indicates the technical format of the target resources signed by the signaturetargetFormat : code [0..1] « The mime type of an attachment. Any valid mime type is allowed. (Strength=Required)MimeTypes! »A mime type that indicates the technical format of the signature. Important mime types are application/signature+xml for X ML DigSig, application/jose for JWS, and image/* for a graphical image of a signature, etcsigFormat : code [0..1] « The mime type of an attachment. Any valid mime type is allowed. (Strength=Required)MimeTypes! »The base64 encoding of the Signature content. When signature is not recorded electronically this element would be emptydata : base64Binary [0..1]DataType

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:type  ( [ Coding ] ... ) ; # 0..* Indication of the reason the entity signed the object(s)
  fhir:when [ instant ] ; # 0..1 When the signature was created
  fhir:who [ Reference(Device|Organization|Patient|Practitioner|PractitionerRole|RelatedPerson) ] ; # 0..1 Who signed
  fhir:onBehalfOf [ Reference(Device|Organization|Patient|Practitioner|PractitionerRole|RelatedPerson) ] ; # 0..1 The party represented
  fhir:targetFormat [ code ] ; # 0..1 The technical format of the signed resources
  fhir:sigFormat [ code ] ; # 0..1 The technical format of the signature
  fhir:data [ base64Binary ] ; # 0..1 The actual signature content (XML DigSig. JWS, picture, etc.)
]

Changes since Release 3

Changes from both R4 and R4B

Signature
Signature.type
  • Min Cardinality changed from 1 to 0
Signature.when
  • Min Cardinality changed from 1 to 0
Signature.who
  • Min Cardinality changed from 1 to 0

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. SignatureTUElementA Signature - XML DigSig, JWS, Graphical image of signature, etc.

Elements defined in Ancestors: id, extension
... typeΣ0..*CodingIndication of the reason the entity signed the object(s)
Binding: Signature Type Codes (Preferred)

... whenΣ0..1instantWhen the signature was created
... whoΣ0..1Reference(Practitioner | PractitionerRole | RelatedPerson | Patient | Device | Organization)Who signed
... targetFormat0..1codeThe technical format of the signed resources
Binding: Mime Types (Required)
... sigFormat0..1codeThe technical format of the signature
Binding: Mime Types (Required)
... data0..1base64BinaryThe actual signature content (XML DigSig. JWS, picture, etc.)

doco Documentation for this format icon

UML Diagram (Legend)

SignatureAn indication of the reason that the entity signed this document. This may be explicitly included as part of the signature information and can be used when determining accountability for various actions concerning the documenttype : Coding [0..*] « An indication of the reason that an entity signed the object. (Strength=Preferred)SignatureTypeCodes? »When the digital signature was signedwhen : instant [0..1]A reference to an application-usable description of the identity that signed (e.g. the signature used their private key)who : Reference [0..1] « Practitioner|PractitionerRole|RelatedPerson| Patient|Device|Organization »A reference to an application-usable description of the identity that is represented by the signatureonBehalfOf : Reference [0..1] « Practitioner|PractitionerRole| RelatedPerson|Patient|Device|Organization »A mime type that indicates the technical format of the target resources signed by the signaturetargetFormat : code [0..1] « The mime type of an attachment. Any valid mime type is allowed. (Strength=Required)MimeTypes! »A mime type that indicates the technical format of the signature. Important mime types are application/signature+xml for X ML DigSig, application/jose for JWS, and image/* for a graphical image of a signature, etcsigFormat : code [0..1] « The mime type of an attachment. Any valid mime type is allowed. (Strength=Required)MimeTypes! »The base64 encoding of the Signature content. When signature is not recorded electronically this element would be emptydata : base64Binary [0..1]DataType

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:type  ( [ Coding ] ... ) ; # 0..* Indication of the reason the entity signed the object(s)
  fhir:when [ instant ] ; # 0..1 When the signature was created
  fhir:who [ Reference(Device|Organization|Patient|Practitioner|PractitionerRole|RelatedPerson) ] ; # 0..1 Who signed
  fhir:onBehalfOf [ Reference(Device|Organization|Patient|Practitioner|PractitionerRole|RelatedPerson) ] ; # 0..1 The party represented
  fhir:targetFormat [ code ] ; # 0..1 The technical format of the signed resources
  fhir:sigFormat [ code ] ; # 0..1 The technical format of the signature
  fhir:data [ base64Binary ] ; # 0..1 The actual signature content (XML DigSig. JWS, picture, etc.)
]

Changes since Release 3

Changes from both R4 and R4B

Signature
Signature.type
  • Min Cardinality changed from 1 to 0
Signature.when
  • Min Cardinality changed from 1 to 0
Signature.who
  • Min Cardinality changed from 1 to 0

See the Full Difference for further information

Constraints

Notes:

  • The Signature datatype can be used to hold a digital-signature, but may also be used to hold electronic-signatures.
  • Electronic-Signatures, such as image of ink signature, do not protect the signed content from change, but do carry details about who signed, when signature happened, and what the signature means.
  • One consequence of digital-signature on a Resource (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.
  • Note that following common normalization procedures in XML can assign the same normalized text to resources with slightly different meanings, since leading whitespace matters in markdown text, and the XML representation serializes the markdown datatype using attributes.

 

When the signature is an XML Digital Signature (contentType = application/signature+xml), the following rules apply:

  • The Signature.data is base64 encoded XML-Signature
  • The XML-Signature is a Detached icon Signature (where the content that is signed is separate from the signature itself)
  • The Signature SHOULD conform to XAdES-X-L icon for support of Long Term signatures icon. The XAdES-X-L specification adds the timestamp of the signing, inclusion of the signing certificate, and statement of revocation
  • When FHIR Resources are signed, the signature is across the Canonical XML form of the resource(s)
  • The Signature SHOULD use the hashing algorithm SHA-256. Signature validation policy will apply to the signature and determine acceptability
  • The Signature SHALL include a "CommitmentTypeIndication" element for the Purpose(s) of Signature. The Purpose can be the action being attested to, or the role associated with the signature. The value shall come from ASTM E1762-95(2013). The Signature.type shall contain the same values as the CommitmentTypeIndication element.

There are three levels of signature verification:

  1. Verifying that the Digital Signature block itself has integrity through verifying the signature across the XML-Signature.
  2. Confirming that the signer was authentic, not revoked, and appropriate to the signature purpose.
  3. Confirming that the signed content of interest is unmodified using the hash algorithm.

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:

  • The Signature.data is base64 encoded JWS-Signature RFC 7515: JSON Web Signature (JWS) icon
  • The signature is a Detached icon Signature (where the content that is signed is separate from the signature itself)
  • When FHIR Resources are signed, the signature is across the Canonical JSON form of the resource(s)
  • The Signature SHOULD use the hashing algorithm SHA-256. Signature validation policy will apply to the signature and determine acceptability
  • The Signature SHALL include a "srCms signer commitments" element for the Purpose(s) of Signature. The Purpose can be the action being attested to, or the role associated with the signature. The value shall come from ASTM E1762-95(2013). The Signature.type shall contain the same values as the srCms element.
  • The Signature SHOULD conform to JAdES-B-LT for support of long term signatures. The JAdES-B-LT specification adds the timestamp of the signing, inclusion of the signing certificate, and statement of revocation

There are three levels of signature verification:

  1. Verifying that the Digital Signature block itself has integrity through verifying the signature across the JWS-Signature.
  2. Confirming that the signer was authentic, not revoked, and appropriate to the signature purpose.
  3. Confirming that the signed content of interest is unmodified using the hash algorithm.

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: Bundle, Contract, Provenance and VerificationResult

FHIR Infrastructure icon Work GroupMaturity Level: 5Standards Status: Normative

See also Examples, Detailed Descriptions, Mappings, Profiles, Extensions and R4 Conversions

A text note which also contains information about who made the statement and when.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. AnnotationNElementText node with attribution

Elements defined in Ancestors: id, extension
... author[x]Σ0..1Individual responsible for the annotation
.... authorReferenceReference(Practitioner | PractitionerRole | Patient | RelatedPerson | Organization)
.... authorStringstring
... timeΣ0..1dateTimeWhen the annotation was made
... textΣ1..1markdownThe annotation - text content (as markdown)

doco Documentation for this format icon

Definition: XML | JSON

XML Template

<Annotation xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <author[x]><!-- 0..1 Reference(Organization|Patient|Practitioner|
   PractitionerRole|RelatedPerson)|string Individual responsible for the annotation --></author[x]>
 <time value="[dateTime]"/><!-- 0..1 When the annotation was made -->
 <text value="[markdown]"/><!-- 1..1 The annotation  - text content (as markdown) -->
</Annotation>

JSON Template

{doco
  // from Element: extension
  // author[x]: Individual responsible for the annotation. One of these 2:
  "authorReference" : { Reference(Organization|Patient|Practitioner|
   PractitionerRole|RelatedPerson) },
  "authorString" : "<string>",
  "time" : "<dateTime>", // When the annotation was made
  "text" : "<markdown>" // R!  The annotation  - text content (as markdown)
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  # author[x] : 0..1 Individual responsible for the annotation. One of these 2
    fhir:author [  a fhir:Reference ; Reference(Organization|Patient|Practitioner|PractitionerRole|RelatedPerson) ]
    fhir:author [  a fhir:string ; string ]
  fhir:time [ dateTime ] ; # 0..1 When the annotation was made
  fhir:text [ markdown ] ; # 1..1 The annotation  - text content (as markdown)
]

Changes since Release 3

Changes from both R4 and R4B

Annotation
  • No Changes

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. AnnotationNElementText node with attribution

Elements defined in Ancestors: id, extension
... author[x]Σ0..1Individual responsible for the annotation
.... authorReferenceReference(Practitioner | PractitionerRole | Patient | RelatedPerson | Organization)
.... authorStringstring
... timeΣ0..1dateTimeWhen the annotation was made
... textΣ1..1markdownThe annotation - text content (as markdown)

doco Documentation for this format icon

XML Template

<Annotation xmlns="http://hl7.org/fhir">
 <!-- from Element: extension -->
 <author[x]><!-- 0..1 Reference(Organization|Patient|Practitioner|
   PractitionerRole|RelatedPerson)|string Individual responsible for the annotation --></author[x]>
 <time value="[dateTime]"/><!-- 0..1 When the annotation was made -->
 <text value="[markdown]"/><!-- 1..1 The annotation  - text content (as markdown) -->
</Annotation>

JSON Template

{doco
  // from Element: extension
  // author[x]: Individual responsible for the annotation. One of these 2:
  "authorReference" : { Reference(Organization|Patient|Practitioner|
   PractitionerRole|RelatedPerson) },
  "authorString" : "<string>",
  "time" : "<dateTime>", // When the annotation was made
  "text" : "<markdown>" // R!  The annotation  - text content (as markdown)
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  # author[x] : 0..1 Individual responsible for the annotation. One of these 2
    fhir:author [  a fhir:Reference ; Reference(Organization|Patient|Practitioner|PractitionerRole|RelatedPerson) ]
    fhir:author [  a fhir:string ; string ]
  fhir:time [ dateTime ] ; # 0..1 When the annotation was made
  fhir:text [ markdown ] ; # 1..1 The annotation  - text content (as markdown)
]

Changes since Release 3

Changes from both R4 and R4B

Annotation
  • No Changes

See the Full Difference for further information

Notes:

  • Systems that do not have structured annotations communicate a single annotation with no author or time.
  • Annotations SHOULD NOT be used to communicate "modifying" information that could be computable (this is a SHOULD because enforcing user behavior is nearly impossible).
  • For communicating the author as a string value, implementers SHOULD use use Annotation.authorReference.display instead of the the anti-pattern Annotation.authorString (authorString cannot be removed because this datatype is Normative).
  • This element may need to be included in the Resource human-readable narrative because of the potential for modifying information.

Annotation is used in the following places: AdverseEvent, AllergyIntolerance, Appointment, BiologicallyDerivedProductDispense, CarePlan, CareTeam, ChargeItem, Citation, ClinicalImpression, Communication, CommunicationRequest, Composition, Condition, Contract, DetectedIssue, Device, DeviceDefinition, DeviceDispense, DeviceRequest, DeviceUsage, DiagnosticReport, Evidence, EvidenceReport, EvidenceVariable, FamilyMemberHistory, GenomicStudy, Goal, GuidanceResponse, ImagingStudy, Immunization, InventoryItem, InventoryReport, Invoice, List, MedicationAdministration, MedicationDispense, MedicationKnowledge, MedicationRequest, MedicationStatement, NutritionIntake, NutritionOrder, NutritionProduct, Observation, Procedure, RequestOrchestration, ResearchStudy, RiskAssessment, ServiceRequest, Specimen, SubstanceDefinition, Task, Transport and VisionPrescription

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:

Primitive Types Datatypes MetaDataTypes Special Types

The element name ends with "[x]", and this is replaced with the Title cased name of the datatype.

Open types are used in the following places: ElementDefinition, Parameters, Task and Transport

The following types are defined as part of the datatypes, but are documented elsewhere in the specification:

DataTypeExtensionSource of the definition for the extension code - a logical name or a URLurl : uri [1..1]Value of extension - must be one of a constrained set of the data types (see [Extensibility](extensibility.html) for a list)value[x] : * [0..1] « This element has or is affected by some invariantsC »NarrativeThe status of the narrative - whether it's entirely generated (from just the defined data or the extensions too), or whether a human authored it and it may contain additional datastatus : code [1..1] « The status of a resource narrative. (Strength=Required)NarrativeStatus! »The actual narrative content, a stripped down version of XHTMLdiv : xhtml [1..1]ReferenceA reference to a location at which the other resource is found. The reference may be a relative reference, in which case it is relative to the service base URL, or an absolute URL that resolves to the location where the resource is found. The reference may be version specific or not. If the reference is not to a FHIR RESTful server, then it should be assumed to be version specific. Internal fragment references (start with '#') refer to contained resourcesreference : string [0..1] « This element has or is affected by some invariantsC »The expected type of the target of the reference. If both Reference.type and Reference.reference are populated and Reference.reference is a FHIR URL, both SHALL be consistent. The type is the Canonical URL of Resource Definition that is the type this reference refers to. References are URLs that are relative to http://hl7.org/fhir/StructureDefinition/ e.g. "Patient" is a reference to http://hl7.org/fhir/StructureDefinition/Patient. Absolute URLs are only allowed for logical models (and can only be used in references in logical models, not resources)type : uri [0..1] « Aa resource (or, for logical models, the URI of the logical model). (Strength=Extensible)ResourceType+ »An identifier for the target resource. This is used when there is no way to reference the other resource directly, either because the entity it represents is not available through a FHIR server, or because there is no way for the author of the resource to convert a known identifier to an actual location. There is no requirement that a Reference.identifier point to something that is actually exposed as a FHIR instance, but it SHALL point to a business concept that would be expected to be exposed as a FHIR instance, and that instance would need to be of a FHIR resource type allowed by the referenceidentifier : Identifier [0..1] « This element has or is affected by some invariantsC »Plain text narrative that identifies the resource in addition to the resource referencedisplay : string [0..1] « This element has or is affected by some invariantsC »
  • Resource - the conceptual base class for all resources
  • Reference - for references from one resource to another
  • Extension - used to convey additional data in a resource
  • Narrative - conveys a human-readable representation of the content of a resource