FHIR datatypes

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. All types follow the FHIR R4 datatypes. 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.

Type	What it holds	Example
string	Free text	`"childhood"`
code	One value from a fixed list. You read it as a plain string.	`"final"`, `"allergy"`, `"female"`
integer	A whole number	`15`
boolean	`true` or `false`	`true`
date	`YYYY`, `YYYY-MM`, or `YYYY-MM-DD`	`"1968-04-02"`
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.	`"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.

Coding

A Coding is one code from one code system. See the R4 definition of 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

{ "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.

Field	Type	Definition
`coding`	list of 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`.

Coded
Two codings
Text only

{
  "coding": [
    { "system": "http://snomed.info/sct", "code": "195967001", "display": "Asthma" }
  ],
  "text": "Asthma"
}

{
  "coding": [
    { "system": "http://hl7.org/fhir/administrative-gender", "code": "female", "display": "Female" },
    { "system": "http://snomed.info/sct", "code": "248152002", "display": "Female" }
  ],
  "text": "Female"
}

{ "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.

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:

[{ "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.

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	The Identifier of the Encounter it points to. Only on `encounter` references.
`display`	string	A name, when there is no resource to point to

Points to the Patient
Points to the Encounter
Names a person

{ "reference": "urn:uuid:b49ecda5-92db-5325-a7a9-f82c71500bad", "type": "Patient" }

{
  "reference": "urn:uuid:29543af8-9ec2-528e-8a3b-1e891822d99d",
  "type": "Encounter",
  "identifier": { "system": "http://corti.app/fhir/identifier/encounter", "value": "enc-88213" }
}

{ "display": "Dr. Patel" }

Quantity

A Quantity is a number with a unit. See the R4 definition of 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`.

{ "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.

Field	Type	Definition
`numerator`	Quantity	The top number
`denominator`	Quantity	The bottom number

{ "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.

Field	Type	Definition
`low`	Quantity	The lower bound
`high`	Quantity	The upper bound

{
  "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.

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

{ "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.

Field	Type	Definition
`text`	string	The note text

[{ "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 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 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.

{
  "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 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.

{
  "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 shows how to use both extensions.

Next steps

Condition resource group

See these datatypes in use on a Condition.

FHIR basics

Learn the ideas behind resources, codes, and Bundles.

Clinical Text Generation

Medical Coding

FHIR Extraction

Clinical Assistant

Primitive types

Coding

CodeableConcept

Identifier

Reference

Quantity

Ratio

Range

Period

Annotation

Extension

Mention

Alternative

Next steps

Condition resource group

FHIR basics

​Primitive types

​Coding

​CodeableConcept

​Identifier

​Reference

​Quantity

​Ratio

​Range

​Period

​Annotation

​Extension

​Mention

​Alternative

​Next steps

Condition resource group

FHIR basics

Primitive types

Coding

CodeableConcept

Identifier

Reference

Quantity

Ratio

Range

Period

Annotation

Extension

Mention

Alternative

Next steps