Kotlin FHIR

Kotlin FHIR is a lean and fast implementation of the HL7® FHIR® data model on Kotlin Multiplatform.

Key features

• Lightweight & fast with a minimal footprint and zero bloat[^1]
• Clean, modern & elegant Kotlin code with minimalistic class definitions
• Code generation[^2] from FHIR specifications for completeness and maintainability
• JSON only[^3], no XML

• Multiplatform support for Android, iOS and web development, with JVM, native

• Support for multiple FHIR versions

[^2]: Using KotlinPoet.

[^3]: It is also possible to serialize to other formats kotlinx.serialization supports, such as protocol buffers. However, there is no XML or Turtle support.

Supported platforms

The library supports the following target platforms:

| Target platform | Gradle target | Artifact suffix | Support | |:-----------------------------------|:--------------|:----------------|:--------| | Kotlin/JVM | jvm | -jvm | ✅ | | Kotlin/Wasm | wasmJs | -wasm-js | ✅ | | Kotlin/Wasm | wasmWasi | -wasm-wasi | ✅ | | Kotlin/JS | js | -js | ✅ | | Android applications and libraries | android | -android | ✅ |

The library also supports the following Kotlin/Native targets:

| Gradle target | Artifact suffix | Tier | Support | |:------------------|:---------------------|:-----|:--------| | iosSimulatorArm64 | -iossimulatorarm64 | 1 | ✅ | | iosArm64 | -iosarm64 | 1 | ✅ |

Data model

Mapping FHIR primitive data types to Kotlin

In FHIR, primitive data types (e.g. in R4) are defined using StructureDefinitions[^4]. For instance, the date type is defined in StructureDefinition-date.json. While primitive, these types may include an id and extensions, preventing direct mapping to Kotlin's primitive types. To resolve this issue, the library generates a distinct Kotlin class for each FHIR primitive data type, for example, the Date class inDate.kt file for the date type.

[^4]: A "JSON Definition" link to the StructureDefinition is now included for each FHIR primitive data type in the Data Types page in FHIR CI-BUILD.

However, the actual values within these FHIR primitive data types defined using FHIRPath types (e.g. the integer.value element in StructureDefinition-integer.json has the FHIRPath type System.Integer) still need to be mapped to Kotlin types in the generated code. The mapping is as follows:

| FHIRPath type | Kotlin type | |-----------------------------------------------------------------------------|-----------------------------------------------------------------------------| | System.Boolean | kotlin.Boolean | | System.String | kotlin.String | | System.Integer | kotlin.Int | | System.Long | kotlin.Long | | System.Decimal | com.ionspin.kotlin.bignum.decimal.BigDecimal | | System.Date | FhirDate | | System.Time | kotlinx.datetime.LocalTime | | System.DateTime | FhirDateTime |

[!NOTE]

Kotlin Multiplatform BigNum

library's BigDecimal is used to preserve and respect the precision of decimal values as required

by the specification. See the notes section in Datatypes.

[!NOTE]

The System.Date and System.DateTime types are mapped to sealed interfaces

FhirDate and FhirDateTime specifically generated to handle partial dates in FHIR. They are

implemented using LocalDate, LocalDateTime and UtcOffset classes in the kotlinx-datetime

library.

Since all FHIR data types are defined using FHIRPath types in their StructureDefinitions, mapping FHIRPath types to Kotlin effectively covers all FHIR data types. For brevity, the full FHIR data type mapping to Kotlin is omitted here. However, notable exceptions exist where the FHIR data type uses a FHIRPath type that is either inconsistent with the base data type, or is unsuitable for represent the data in Kotlin. These exceptions are listed below:

| FHIR data type | FHIRPath type | Kotlin type | |------------------------------------------------------------------------------|-----------------------------------------------------------------------------|-----------------------------------------------------------------------------| | positiveInt | System.String | Kotlin.Int | | unsignedInt | System.String | Kotlin.Int |

Mapping FHIR data structure to Kotlin

Similarly, for more complex data structures in FHIR such as complex data types and FHIR resources, the library maps each StructureDefinition JSON file to a dedicated Kotlin .kt file, each containing a Kotlin data class representing the StructureDefinition. BackboneElements in FHIR are represented as nested data classes since they are never reused outside the StructureDefinition. For each occurrence of a choice type (e.g. in R4), a single sealed interface is generated with a subclass for each type.

| FHIR concept | Kotlin concept | |----------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| | StructureDefinition JSON file (e.g. StructureDefinition-Patient.json) | Kotlin .kt file (e.g. Patient.kt) | | StructureDefinition (e.g. Patient) | Kotlin data class (e.g. data class Patient) | | BackboneElement (e.g. Patient.contact) | Nested Kotlin data class (e.g. data class Contact nested under Patient) | | Choice of data types (e.g. Patient.deceased[x]) | Sealed interface (e.g. sealed interface Deceased nested under Patient with subtypes Boolean and DateTime) |

The generated FHIR resource classes are Kotlin data classes. They are compact and readable, with automatically generated methods: equals()/hashCode(), toString(), componentN() functions, and copy().

The use of sealed interfaces for choice of data types, combined with Kotlin's smart casts, eliminates boilerplate type checks and makes code cleaner, more type-safe, and easier to write. This is particularly true when used in when statements:

when (val multipleBirth = patient.multipleBirth) {
    is Patient.MultipleBirth.Boolean -> {
        // Smart cast to Boolean
        println("Whether patient is part of a multiple birth: ${multipleBirth.value.value}")
    }
is Patient.MultipleBirth.Integer -> {         // Smart cast to Integer         println("Birth order: ${multipleBirth.value.value}")     }
null -> {         // Do nothing     } }

The generated classes reflect the inheritance hierarchy defined by FHIR. For example, Patient inherits from DomainResource, which inherits from Resource.

Mapping FHIR ValueSets to Kotlin Enums

Kotlin enums classes are generated for value sets referenced by elements via binding. The constants in the generated enum classes are derived from the code property of the expanded CodeSystem concepts in the expansion packages. The value sets that are not bound to elements are excluded from code generation.

Shared vs. Local Enums

• If the StructureDefinition defines an element with a common binding, a shared enum is generated and placed in the dev.ohs.fhir.model.<r4|r4b|r5>.terminologies package.

• If the element uses a non-common binding, a local enum is created inside the associated parent class.

Enum Naming and Content

The enum constants are derived from ValueSet definitions in the expansion packages for R4, R4B, and R5. Each ValueSet includes codes from one or more CodeSystem resources it references.

| FHIR concept | Kotlin concept | |----------------------------------------------------------------------------|--------------------------------------------------------------------------------| | ValueSet JSON file (e.g. ValueSet-resource-types.json) | Kotlin .kt file (e.g. ResourceType) | | ValueSet (e.g. ResourceType) | Kotlin class (e.g. enum class ResourceType) |

To comply with Kotlin’s enum naming convention—which requires names to start with a letter and avoid special characters—each code is transformed using a set of formatting rules. This includes handling numeric codes, special characters, and FHIR URLs. After all transformations, the final name is converted to PascalCase to match Kotlin style guidelines.

| Rule # | Description | Example Input | Example Output | |--------|-----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|------------------------| | 1 | For codes that are full URLs, extract and return the last segment after the dot | http://hl7.org/fhirpath/System.DateTime from CodeSystem-fhirpath-types | DateTime | | 2 | Specific special characters are replaced with readable keywords | >= from CodeSystem-quantity-comparator | GreaterThanOrEqualTo | | | | > | GreaterThan | | | | < | LessThan | | | | <= | LessThanOrEqualTo | | | | != or <> | NotEqualTo | | | | = | EqualTo | | | | * | Multiply | | | | + | Plus | | | | - | Minus | | | | / | Divide | | | | % | Percent | | 3.1 | Replace all non-alphanumeric characters including dashes (-) and dots (.) with underscore | 4.0.1 from CodeSystem-FHIR-version | 40_1 | | 3.2 | Prefix codes starting with a digit with an underscore | 4.0.1 from CodeSystem-FHIR-version | 401 | | 3.3 | Apply PascalCase to each segment between underscores while preserving the underscores | entered-in-error from CodeSystem-document-reference-status | EnteredIn_Error |

Excluded ValueSets from Enum Generation

The following FHIR value sets are excluded from Kotlin enum generation.

| ValueSet URL | Reason for Exclusion | Affected Version(s) | |--------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|---------------------| | http://hl7.org/fhir/ValueSet/mimetypes | This value set cannot be expanded because of the way it is defined - it has an infinite number of members | R4, R4B, R5 | | http://hl7.org/fhir/ValueSet/all-languages | This value set cannot be expanded because of the way it is defined - it has an infinite number of members | R4, R4B, R5 | | http://hl7.org/fhir/ValueSet/use-context | This value set has >3800 codes when expanded; generated enum class code cannot compile. | R4, R4B, R5 |

Search Parameters

Search parameters are generated from the SearchParameter resource definitions in the FHIR specification packages (e.g. SearchParameter-*.json under third_party/) and placed in the search subpackage of each FHIR version (e.g. dev.ohs.fhir.model.r4.search). Each resource type has a {Resource}SearchParams object (e.g. PatientSearchParams) containing:

• One val per search parameter, typed SearchParam<R, T> where R is the resource type and T is the value type.
• An all list of all supported search parameters.
• An unsupported list of unsupported search parameters.

| Member | Type | Description | |:--------------|:-----------------------------|:----------------------------------------------------------------------------------| | name | String | The search parameter name as used in search URLs. | | type | SearchParamType | The search parameter type (number, date, string, token, …). | | expression | String | The FHIRPath expression that extracts values for this param. | | target | List<KClass<out Resource>> | Target resource types for reference search parameters. | | extractFrom | (resource: R) -> List<T> | Pulls the values of type T out of a resource of type R for this search param. |

Supported FHIRPath patterns

The following FHIRPath patterns produce a typed extractFrom():

| Pattern | Example | Notes | |:----------------------------------|:----------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------| | Simple property | Patient.birthDate | | | Nested path | Patient.address.city | | | List property | Patient.identifier | | | Element cast (X.path as Type) | (Patient.deceased as dateTime) | | | Element cast X.path.as(Type) | Condition.onset.as(dateTime) | | | Element (no cast) | ChargeItem.occurrence | Returns the sealed interface ChargeItem.Occurrence itself rather than the underlying DateTime / Period / Timing. | | where(resolve() is Type) filter | Account.subject.where(resolve() is Patient) | Substring-matches Reference.reference against Type/. Misses URN-form (urn:uuid:…), contained (#id), and Reference.type-only references. | | where(field='value') filter | Patient.telecom.where(system='email') | |

Unsupported FHIRPath patterns

Some FHIRPath expressions aren't supported yet. For those parameters, extractFrom() throws NotImplementedError and the type parameter is Any. The container's unsupported property lists them explicitly, and all excludes them so iterating all and calling extractFrom is safe. The rest of the metadata (name, type, expression, target) is still populated, so callers that want these parameters can read the expression string and evaluate it with a FHIRPath engine instead.

206 such parameters across R4 / R4B / R5 fall into the following categories. See unsupported-search-params.md for the full per-category list.

| Pattern | Count | Example | Full list | |:----------------------------------------------------|------:|:-----------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------| | .ofType(Type) choice narrowing | 118 | Observation.value.ofType(Quantity) | of-type | | Empty FHIRPath expression | 28 | Patient.age, Resource.content | empty | | .extension('url') access | 20 | Patient.extension('http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName') | extension | | Composite search parameters with no component path | 13 | Observation's code-value-quantity | composite | | Boolean logic | 5 | Resource.deceased.exists() and Resource.deceased != false | boolean-logic | | Multi-resource union without a resource prefix | 3 | name \| alias for InsurancePlan's name parameter | union | | Other where(...) conditions | 3 | QuestionnaireResponse's item-subject parameter | where | | Other patterns (parens, indexed access, bare paths) | 16 | (Citation.classification.type), Bundle.entry[0].resource | other |

graph TB
    A["Patient instance"] -->|"json.encodeToString(patient)"| PS["PatientSerializer<br/>writes resourceType + fields"]
    A -->|"json.encodeToString&ltResource&gt(patient)"| RPS["ResourcePolymorphicSerializer<br/>(AbstractPolymorphicSerializer)"]
    RPS -->|"byClass[Patient::class]"| PPS["PatientPolymorphicSerializer<br/>writes fields only"]
    RPS -.->|"kotlinx-json injects<br/>resourceType discriminator"| O
    PS --> O["JSON output<br/>{ resourceType, ... }"]
    PPS --> O

graph LR
    A["Patient JSON
    {
    #nbsp;#nbsp;gender: ...
    #nbsp;#nbsp;_gender: ...
    #nbsp;#nbsp;deceasedBoolean: ...
    #nbsp;#nbsp;deceasedDateTime: ...
    #nbsp;#nbsp;multipleBirthBoolean: ...
    #nbsp;#nbsp;_multipleBirthBoolean: ...
    #nbsp;#nbsp;multipleBirthInteger: ...
    #nbsp;#nbsp;contact: [...]
    }
    "]
    E["Patient object
    gender: Code
    deceased: Patient.Deceased
    #nbsp;#nbsp;↳ .Boolean | .DateTime
    multipleBirth: Patient.MultipleBirth
    #nbsp;#nbsp;↳ .Boolean | .Integer
    contact: List<Patient.Contact>
    "]
subgraph PS["PatientSerializer  (descriptorOffset = 1)"]       direction TB       Desc["descriptor       0 → resourceType       ...       16 → gender / 17 → _gender       20 → deceasedBoolean / 21 → _deceasedBoolean       22 → deceasedDateTime / 23 → _deceasedDateTime       26 → multipleBirthBoolean / 27 → _multipleBirthBoolean       28 → multipleBirthInteger / 29 → _multipleBirthInteger       31 → contact / 32 → communication / 35 → link"]
Loop["while (true) {       #nbsp;#nbsp;val i = decoder.decodeElementIndex(descriptor)       #nbsp;#nbsp;if (i == DECODE_DONE) break       #nbsp;#nbsp;when (i - descriptorOffset) {       #nbsp;#nbsp;#nbsp;#nbsp;-1 → resourceType discarded       #nbsp;#nbsp;#nbsp;#nbsp;0..33 → per-key wire locals       #nbsp;#nbsp;}       }"]
Loop -- "JSON key → i lookup" --> Desc       Desc -. "return i" .-> Loop       Loop -- "when(16/17) gender, when(20..23) deceased expansions, when(26..29) multipleBirth expansions, ..." --> Locals[per-key locals]       Locals -- "MultipleBirth.from(boolean, boolean, integer, integer)" --> Seal[sealed values synthesized]       Locals -- "Deceased.from(boolean, boolean, dateTime, dateTime)" --> Seal       Locals -- "PatientContact / Communication / LinkSerializer.deserialize" --> BB[backbone elements]     end
A --> PS     Seal --> E     BB --> E     Locals --> E
style A text-align:left     style E text-align:left     style Desc text-align:left     style Loop text-align:left     style PS stroke-dasharray: 5 5

graph LR
    subgraph Gradle binary plugin
        A(FHIR spec<br>in JSON) -- kotlinx.serialization --> B(instances of<br>StructureDefinition<br>Kotlin data class<br>)
        B -- KotlinPoet --> C[generated FHIR Resource classes]
    end
    C -- compiler --> D[Kotlin/JVM]
    C -- compiler --> E[Kotlin/Wasm]
    C -- compiler --> F[KotlinJS]
    C -- compiler --> G[Kotlin/Native]
    C -- compiler --> H[Android]

// build.gradle.kts
repositories {
    // Other repositories such as gradlePluginPortal() and google()
    mavenCentral()
}

// e.g., composeApp/build.gradle.kts or shared/build.gradle.kts
kotlin {
    sourceSets {
        commonMain.dependencies {
            // Use only the FHIR version(s) you need:
            implementation("dev.ohs.fhir:fhir-model-r4:1.0.0-beta05")
// Or include all versions at once:             // implementation("dev.ohs.fhir:fhir-model:1.0.0-beta05")         }     } }

// e.g., app/build.gradle.kts
dependencies {
    implementation("dev.ohs.fhir:fhir-model-r4:1.0.0-beta05")
}

// e.g., build.gradle.kts
dependencies {
    // Gradle's variant-aware resolution automatically fetches the JVM target variant
    implementation("dev.ohs.fhir:fhir-model-r4:1.0.0-beta05")
}

<!-- e.g., pom.xml -->
<dependency>
    <groupId>dev.ohs.fhir</groupId>
    <artifactId>fhir-model-r4-jvm</artifactId>
    <version>1.0.0-beta05</version>
</dependency>

import dev.ohs.fhir.model.r4.Date
import dev.ohs.fhir.model.r4.FhirDate
import dev.ohs.fhir.model.r4.HumanName
import dev.ohs.fhir.model.r4.Patient
import dev.ohs.fhir.model.r4.String as FhirString
fun main() {     val patient = Patient(         id = "patient-01",         name = listOf(             HumanName(                 given = listOf(FhirString(value = "John"))             )         ),         birthDate = Date(value = FhirDate.fromString("2000-01-01"))     ) }

import dev.ohs.fhir.model.r4.Date
import dev.ohs.fhir.model.r4.FhirDate
import dev.ohs.fhir.model.r4.HumanName
import dev.ohs.fhir.model.r4.Patient
import dev.ohs.fhir.model.r4.String as FhirString
fun main() {     val patient = Patient.Builder()         .apply {             id = "patient-01"             name.add(                 HumanName.Builder().apply {                     given.add(FhirString.Builder().apply { value = "John" })                 }             )             birthDate = Date.Builder().apply { value = FhirDate.fromString("2000-01-01") }         }         .build() }

val updated = patient.copy(
    id = "patient-02",
    birthDate = Date(value = FhirDate.fromString("1990-06-15"))
)

val updated = patient.toBuilder().apply {
    name.add(
        HumanName.Builder().apply {
            given.add(FhirString.Builder().apply { value = "Jane" })
        }
    )
}.build()

import dev.ohs.fhir.model.r4.search.PatientSearchParams
val birthdates: List<Date> = PatientSearchParams.birthdate.extractFrom(patient)

import dev.ohs.fhir.model.r4.search.extract
val birthdates: List<Date> = patient.extract(PatientSearchParams.birthdate)

import dev.ohs.fhir.model.r4.search.PatientSearchParams
PatientSearchParams.all.forEach { searchParam ->     val values = searchParam.extractFrom(patient)     // ... }

import kotlinx.serialization.json.Json
// See https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/json.md#json-configuration val json = Json {     // No effect on FHIR serialization:     // explicitNulls, encodeDefaults, useAlternativeNames,     // serializersModule (assuming you don't override FHIR resources), classDiscriminator
// Safe to use, but may affect serialization:     // ignoreUnknownKeys, isLenient, allowComments, allowTrailingComma, prettyPrintIndent,     // coerceInputValues, decodeEnumsCaseInsensitive
// Incompatible with FHIR:     // useArrayPolymorphism, namingStrategy }

import kotlinx.serialization.encodeToString
val serializedPatient = json.encodeToString(patient)

import dev.ohs.fhir.model.r4.OperationOutcome
import dev.ohs.fhir.model.r4.Patient
import dev.ohs.fhir.model.r4.Resource
import kotlinx.serialization.decodeFromString
val patientJson = """     {       "resourceType": "Patient",       "id": "example",       "name": [         {           "use": "official",           "family": "Doe",           "given": ["Jane"]         }       ],       "gender": "female",       "birthDate": "1985-03-15"     } """.trimIndent()
// Deserialize to a specific type when you know the resource type val patient = json.decodeFromString<Patient>(patientJson)
// Deserialize to Resource when the type is unknown val resource = json.decodeFromString<Resource>(patientJson)
// Then handle the resource based on the type when (resource) {     is OperationOutcome -> { / parse error / }     is Patient -> { / parse patient / }     else -> { / other resource types / } }

# Generate models for all FHIR versions (R4, R4B, R5) at once:
./gradlew codegen
Generate models for a specific FHIR version (r4, r4b, or r5):
./gradlew :fhir-model-<FHIR_VERSION>:codegen

./gradlew verifyCodegen