---
type: "datatype"
title: "Quantity"
datatype: "Quantity"
---
# Quantity

- [Datatypes](/datatypes)
- [Definitions](/datatypes-definitions#Quantity)
- [Examples](/datatypes-examples#Quantity)
- [Mappings](/datatypes-mappings#Quantity)
- [Profiles](/datatypes-profiles#Quantity)

## Overview

See also [Examples](datatypes-examples#Quantity), [Detailed Descriptions](datatypes-definitions#Quantity), [Mappings](datatypes-mappings#Quantity), [Profiles](datatypes-profiles#Quantity) and [Extensions]([%extensions-location%]extensions-datatypes#Quantity)

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

This datatype can be [bound](terminologies#Quantity) to a [ValueSet](valueset).

\[%dt Quantity 4%\]

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](#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.

If there is a need to convey exceptional values such as Not a Number (NaN), 'trace', 'sufficient quantity', etc., this should be done using a coded data type such as CodeableConcept, drawing on codes from code systems such as [Data Absent Reason](https://terminology.hl7.org/CodeSystem-data-absent-reason.html) or [Null Flavor](https://terminology.hl7.org/CodeSystem-v3-NullFlavor.html), and appropriate extensions exist for this purpose ([here](https://hl7.org/fhir/extensions/StructureDefinition-data-absent-reason.html) and [here](https://hl7.org/fhir/extensions/StructureDefinition-iso21090-nullFlavor.html)).

**Constraints**

\[%dt.constraints Quantity%\]

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](terminologies) for information about binding a Quantity to a [value set](valueset) to constrain the unit codes. The context of use may also restrict the values for the `value` or `comparator`.

\[%tx Quantity%\]

Quantity is used in the following places: \[%dtusage Quantity%\]

### Defined Variations on Quantity

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.

#### Distance

| **Type Name** | **Rules** | **Formal Definitions** |
| --- | --- | --- |
| Distance | \[%dt.constraints Distance%\]\[%tx Distance%\] | [XML](distance.profile.xml), [JSON](distance.profile.json) |
|  | Usage: \[%dtusage Distance%\] |
|  | \[%impl-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). \[%end-note%\] |

#### Distance

| Age | \[%dt.constraints Age%\] \[%tx Age%\] | [XML](age.profile.xml), [JSON](age.profile.json) |
| --- | --- | --- |
| Note: Age intentionally carries the semantics of a duration of time during which an organism (or a process) has existed. |
|  | Usage: \[%dtusage Age%\] |

#### Count

| Count | \[%dt.constraints Count%\] | [XML](count.profile.xml), [JSON](count.profile.json) |
| --- | --- | --- |
|  | Usage: \[%dtusage Count%\] |

#### Duration

| Duration | \[%dt.constraints Duration%\] \[%tx Duration%\] | [XML](duration.profile.xml), [JSON](duration.profile.json) |
| --- | --- | --- |
| Note: Duration intentionally carries the semantics of a length of time. |
|  | Usage: \[%dtusage Duration%\] |

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

#### Simple Quantity

| **Profile Name** | **Rules** | **Formal Definitions** |
| --- | --- | --- |
| Simple Quantity | \[%dt.constraints SimpleQuantity%\] | [XML](simplequantity.profile.xml), [JSON](simplequantity.profile.json) |
|  | Usage: \[%dtusage SimpleQuantity%\] |

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.

## Elements

- **[Quantity.value](/datatypes-definitions#Quantity.value)** [0..1]: [decimal](/decimal) The value of the measured amount. The value includes an implicit precision in the presentation of the value
- **[Quantity.comparator](/datatypes-definitions#Quantity.comparator)** [0..1]: [code](/code) 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
- **[Quantity.unit](/datatypes-definitions#Quantity.unit)** [0..1]: [string](/string) A human-readable form of the unit
- **[Quantity.system](/datatypes-definitions#Quantity.system)** [0..1]: [uri](/uri) The identification of the system that provides the coded form of the unit
- **[Quantity.code](/datatypes-definitions#Quantity.code)** [0..1]: [code](/code) A computer processable form of the unit in some unit representation system

## Bindings

- **Quantity.comparator**: `QuantityComparator` | strength: code list | reference: #quantity-comparator
- **Quantity.code**: `!`

## Modifiers

- **Quantity.comparator**: Is modifier

## Requirements

- **Quantity.value**: Precision is handled implicitly in almost all cases of measurement
- **Quantity.comparator**: Need a framework for handling measures where the value is <5ug/L or >400mg/L due to the limitations of measuring methodology.
- **Quantity.unit**: There are many representations for units of measure and in many contexts, particular representations are fixed and required. I.e. mcg for micrograms
- **Quantity.system**: Need to know the system that defines the coded form of the unit
- **Quantity.code**: Need a computable form of the unit that is fixed across all forms. UCUM provides this for quantities, but SNOMED CT provides many units of interest

## Comments

- **Quantity.value**: The implicit precision in the value should always be honored. Monetary values have their own rules for handling precision (refer to standard accounting text books)
- **Quantity.code**: The preferred system is UCUM, but SNOMED CT can also be used (for customary units) or ISO 4217 for currency. The context of use may additionally require a code from a particular system

## Order and Missing Meaning

- **Quantity.comparator**: Missing: If there is no comparator, then there is no modification of the value

## Mappings

- **Quantity.value**: RIM Mapping: PQ.value, CO.value, MO.value, IVL.high or IVL.low depending on the value
- **Quantity.value**: v2 Mapping: SN.2 / CQ - N/A
- **Quantity.comparator**: RIM Mapping: IVL properties
- **Quantity.comparator**: v2 Mapping: SN.1 / CQ.1
- **Quantity.unit**: RIM Mapping: PQ.unit
- **Quantity.unit**: v2 Mapping: (see OBX.6 etc.) / CQ.2
- **Quantity.system**: RIM Mapping: CO.codeSystem, PQ.translation.codeSystem
- **Quantity.system**: v2 Mapping: (see OBX.6 etc.) / CQ.2
- **Quantity.code**: RIM Mapping: PQ.code, MO.currency, PQ.translation.code
- **Quantity.code**: v2 Mapping: (see OBX.6 etc.) / CQ.2