> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corti.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# FHIR datatypes

> Look up the FHIR R4 datatypes that FHIR Extraction resources use, such as CodeableConcept, Reference, Quantity, and the Corti extensions

The field tables on the resource group pages list a type for every field, such as CodeableConcept or Quantity. This page describes each of those types once, with its fields and an example. For an introduction to the ideas behind them, read [FHIR basics](https://docs.corti.ai/fhir/fhir-basics.md).

All types follow the [FHIR R4 datatypes](https://hl7.org/fhir/R4/datatypes.html). The endpoint leaves out every field that has no value.

## Primitive types

Primitive types hold a single value. Each type links to its [R4 definition](https://hl7.org/fhir/R4/datatypes.html#primitive).

| Type | What it holds | Example |
| - | - | - |
| [string](https://hl7.org/fhir/R4/datatypes.html#string) | Free text | `"childhood"` |
| [code](https://hl7.org/fhir/R4/datatypes.html#code) | One value from a fixed list. You read it as a plain string. | `"final"`, `"allergy"`, `"female"` |
| [integer](https://hl7.org/fhir/R4/datatypes.html#integer) | A whole number | `15` |
| [boolean](https://hl7.org/fhir/R4/datatypes.html#boolean) | `true` or `false` | `true` |
| [date](https://hl7.org/fhir/R4/datatypes.html#date) | `YYYY`, `YYYY-MM`, or `YYYY-MM-DD` | `"1968-04-02"` |
| [dateTime](https://hl7.org/fhir/R4/datatypes.html#dateTime) | A date, or a full date with a time of day. A time always carries seconds and a timezone offset, as R4 requires. The endpoint never adds a timezone the note does not state, so a time without one is cut back to its date. See [How the response meets FHIR R4](https://docs.corti.ai/fhir/how-it-works.md#how-the-response-meets-fhir-r4). | `"2026"`, `"2026-04-03"`, `"2026-04-03T14:20:00+02:00"` |

Fields ending in `DateTime`, such as `onsetDateTime`, use dateTime. Fields ending in `String`, such as `onsetString`, use string. See [choice fields](https://docs.corti.ai/fhir/fhir-basics.md#choice-fields).

## Coding

A Coding is one code from one code system. See the [R4 definition of Coding](https://hl7.org/fhir/R4/datatypes.html#Coding).

| Field | Type | Definition |
| - | - | - |
| `system` | string | The URI of the code system |
| `version` | string | The version of the code system, when known |
| `code` | string | The code |
| `display` | string | The code system's label for the code |

```json theme={null}
{ "system": "http://loinc.org", "code": "8480-6", "display": "Systolic blood pressure" }
```

The code systems you meet in a response:

| `system` | Code system | Used for |
| - | - | - |
| `http://snomed.info/sct` | SNOMED CT | Clinical codes, body sites, severities, qualifiers |
| `http://loinc.org` | LOINC | Lab results, vital signs, survey scores, and other measurements |
| `http://unitsofmeasure.org` | UCUM | Units in a Quantity |
| `http://terminology.hl7.org/CodeSystem/...` | HL7 code systems | Statuses, categories, encounter class and priority, interpretation, relationships |
| `http://hl7.org/fhir/...` | FHIR value sets | Administrative gender, in FamilyMemberHistory `sex` |

Encounter `class` is the only field that holds a bare Coding. Everywhere else, a Coding sits inside a CodeableConcept.

## CodeableConcept

A CodeableConcept is a coded value: one or more Codings that mean the same thing, plus a text label. See the [R4 definition of CodeableConcept](https://hl7.org/fhir/R4/datatypes.html#CodeableConcept).

| Field | Type | Definition |
| - | - | - |
| `coding` | list of [Coding](#coding) | The codes. When there are two, the first is the FHIR value-set code and the second is the SNOMED CT equivalent. |
| `text` | string | A human-readable label. The endpoint fills it from the first `display`. |

> [tab] Coded
>
> ```json theme={null}
> {
>   "coding": [
>     { "system": "http://snomed.info/sct", "code": "195967001", "display": "Asthma" }
>   ],
>   "text": "Asthma"
> }
> ```

> [tab] Two codings
>
> ```json theme={null}
> {
>   "coding": [
>     { "system": "http://hl7.org/fhir/administrative-gender", "code": "female", "display": "Female" },
>     { "system": "http://snomed.info/sct", "code": "248152002", "display": "Female" }
>   ],
>   "text": "Female"
> }
> ```

> [tab] Text only
>
> ```json theme={null}
> { "text": "Suspected appendicitis" }
> ```

A text-only CodeableConcept holds something the endpoint does not code, such as the reason for a procedure.

## Identifier

An Identifier is a business ID for a resource, such as a patient number. See the [R4 definition of Identifier](https://hl7.org/fhir/R4/datatypes.html#Identifier).

| Field | Type | Definition |
| - | - | - |
| `system` | string | The namespace of the ID: `http://corti.app/fhir/identifier/patient` or `http://corti.app/fhir/identifier/encounter` |
| `value` | string | The ID. Your own ID when you send one, otherwise a generated one. |

Patient and Encounter carry `identifier` as a list with one Identifier:

```json theme={null}
[{ "system": "http://corti.app/fhir/identifier/patient", "value": "pat-10442" }]
```

## Reference

A Reference points from one resource to another, or names someone the note mentions. See the [R4 definition of Reference](https://hl7.org/fhir/R4/references.html#Reference).

| Field | Type | Definition |
| - | - | - |
| `reference` | string | The `fullUrl` of the resource it points to in the same Bundle, such as `urn:uuid:29543af8-9ec2-528e-8a3b-1e891822d99d` |
| `type` | string | The resource type it points to, for example `Patient` or `Encounter` |
| `identifier` | [Identifier](#identifier) | The Identifier of the Encounter it points to. Only on `encounter` references. |
| `display` | string | A name, when there is no resource to point to |

> [tab] Points to the Patient
>
> ```json theme={null}
> { "reference": "urn:uuid:b49ecda5-92db-5325-a7a9-f82c71500bad", "type": "Patient" }
> ```

> [tab] Points to the Encounter
>
> ```json theme={null}
> {
>   "reference": "urn:uuid:29543af8-9ec2-528e-8a3b-1e891822d99d",
>   "type": "Encounter",
>   "identifier": { "system": "http://corti.app/fhir/identifier/encounter", "value": "enc-88213" }
> }
> ```

> [tab] Names a person
>
> ```json theme={null}
> { "display": "Dr. Patel" }
> ```

## Quantity

A Quantity is a number with a unit. See the [R4 definition of Quantity](https://hl7.org/fhir/R4/datatypes.html#Quantity).

| Field | Type | Definition |
| - | - | - |
| `value` | decimal | The number |
| `comparator` | code | `<`, `<=`, `>=`, or `>`, when the note gives a limit, such as "CRP \< 5" |
| `unit` | string | The unit, as text |
| `system` | string | `http://unitsofmeasure.org` (UCUM) when there is a unit |
| `code` | string | The UCUM code of the unit. Only ages in FamilyMemberHistory carry it, as `a` for years. Observation units have no `code`. |

```json theme={null}
{ "value": 7.2, "unit": "%", "system": "http://unitsofmeasure.org" }
```

FamilyMemberHistory uses a Quantity in `onsetAge`, for the age at which a relative got a condition.

## Ratio

A Ratio is one Quantity divided by another, such as a titer of "1:64". See the [R4 definition of Ratio](https://hl7.org/fhir/R4/datatypes.html#Ratio).

| Field | Type | Definition |
| - | - | - |
| `numerator` | [Quantity](#quantity) | The top number |
| `denominator` | [Quantity](#quantity) | The bottom number |

```json theme={null}
{ "numerator": { "value": 1 }, "denominator": { "value": 64 } }
```

## Range

A Range is a span between two Quantities, such as "in her 50s". See the [R4 definition of Range](https://hl7.org/fhir/R4/datatypes.html#Range).

| Field | Type | Definition |
| - | - | - |
| `low` | [Quantity](#quantity) | The lower bound |
| `high` | [Quantity](#quantity) | The upper bound |

```json theme={null}
{
  "low": { "value": 50, "unit": "years", "system": "http://unitsofmeasure.org", "code": "a" },
  "high": { "value": 59, "unit": "years", "system": "http://unitsofmeasure.org", "code": "a" }
}
```

## Period

A Period is a span between two points in time. See the [R4 definition of Period](https://hl7.org/fhir/R4/datatypes.html#Period).

| Field | Type | Definition |
| - | - | - |
| `start` | dateTime | When it started |
| `end` | dateTime | When it ended. Missing while it is ongoing. |

```json theme={null}
{ "start": "2026-04-03T14:20:00+02:00", "end": "2026-04-08T10:00:00+02:00" }
```

## Annotation

An Annotation is a free-text note. The `note` field on every clinical resource is a list of Annotations. See the [R4 definition of Annotation](https://hl7.org/fhir/R4/datatypes.html#Annotation).

| Field | Type | Definition |
| - | - | - |
| `text` | string | The note text |

```json theme={null}
[{ "text": "Patient reports symptoms worse at night." }]
```

## Extension

An Extension adds data that FHIR R4 has no field for. Systems that do not know an extension ignore it. See [Extensibility](https://hl7.org/fhir/R4/extensibility.html) in the R4 specification. A resource can carry two kinds of Corti extensions in its `extension` list. Patient and Encounter carry only mentions.

### Mention

A mention links one field of the resource to the words in the note that support it. The [Mention extension](https://docs.corti.ai/fhir/StructureDefinition/mention.md) page has the full definition.

| Sub-extension `url` | Value | Definition |
| - | - | - |
| `field` | `valueString` | The field the mention supports, for example `code` or `valueQuantity` |
| `evidence` | nested `start`, `end`, `text`, `sectionId`, `sectionStart`, `sectionEnd` | One span of the note. `start` and `end` are character offsets into the whole note, with `end` excluded. When the request sends sections, `sectionId` names the section the span comes from, and `sectionStart` and `sectionEnd` are offsets into its title and body. A mention can hold several. |

```json theme={null}
{
  "url": "https://docs.corti.ai/fhir/StructureDefinition/mention",
  "extension": [
    { "url": "field", "valueString": "code" },
    {
      "url": "evidence",
      "extension": [
        { "url": "start", "valueInteger": 5 },
        { "url": "end", "valueInteger": 11 },
        { "url": "text", "valueString": "asthma" }
      ]
    }
  ]
}
```

### Alternative

An alternative lists up to 10 other codes that could also fit a field. The [Alternative extension](https://docs.corti.ai/fhir/StructureDefinition/alternative.md) page has the full definition.

| Sub-extension `url` | Value | Definition |
| - | - | - |
| `field` | `valueString` | The field, either `code`, `bodySite`, or `condition.code` |
| `alternative` | `valueCodeableConcept` | One alternative code. An alternative extension can hold several. |

```json theme={null}
{
  "url": "https://docs.corti.ai/fhir/StructureDefinition/alternative",
  "extension": [
    { "url": "field", "valueString": "code" },
    {
      "url": "alternative",
      "valueCodeableConcept": {
        "coding": [
          { "system": "http://snomed.info/sct", "code": "443694000", "display": "Uncontrolled type 2 diabetes mellitus" }
        ],
        "text": "Uncontrolled type 2 diabetes mellitus"
      }
    }
  ]
}
```

[Every value points back to the note](https://docs.corti.ai/fhir/how-it-works.md#every-value-points-back-to-the-note) shows how to use both extensions.

## Next steps

> [card] [Condition resource group](https://docs.corti.ai/fhir/resource-groups/condition.md)
>
> See these datatypes in use on a Condition.

> [card] [FHIR basics](https://docs.corti.ai/fhir/fhir-basics.md)
>
> Learn the ideas behind resources, codes, and Bundles.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.