Skip to main content
Open Health StackSoftware Foundation
GitHub ↗
Docs/Kotlin FHIR
On this page ⌄
Component overview

Kotlin FHIR

A lean, code-generated implementation of the FHIR data model for Kotlin Multiplatform, with JSON serialization.

What it is​

Kotlin FHIR is the base of the FHIR Foundations stack. It provides the HL7 FHIR data model, every resource and data type, generated as minimalistic and idiomatic Kotlin classes, together with kotlinx.serialization serializers that read and write spec-compliant FHIR JSON. It covers FHIR R4, R4B, and R5, each as its own artifact.

The library is deliberately lean. It carries no logging, no networking, no XML machinery, and no platform-specific dependencies, which is what lets it target everything from Android and iOS to Wasm and native Linux. Its only runtime dependencies are kotlinx-serialization, kotlinx-datetime, and an arbitrary-precision number library.

What you get​

  • Resource and data-type classes for the full FHIR specification, generated from the official spec packages. Choice elements (value[x]) become sealed interfaces, so the compiler enforces which types an element accepts.
  • Enums for coded fields where the spec binds a required ValueSet, including a shared terminologies package for bindings used across many resources (such as AdministrativeGender).
  • Hand-written primitive types where Kotlin needs help matching FHIR semantics. FhirDate and FhirDateTime model FHIR's variable-precision dates, and FhirDecimal preserves arbitrary precision.
  • Generated serializers that handle FHIR JSON's quirks, such as primitive elements with extensions (the _field convention), polymorphic resource decoding via the resourceType discriminator, and choice-type expansion. You use a plain kotlinx.serialization.Json instance.
  • Generated search-parameter extractors. For each resource there is a SearchParams object whose parameters extract values as native Kotlin code, without needing a runtime FHIRPath engine. The FHIRPath expression string is still carried as metadata for callers that want to evaluate it externally. That seam is where Kotlin FHIRPath plugs in.

Artifacts​

ArtifactContents
fhir-model-r4FHIR R4 model, package dev.ohs.fhir.model.r4
fhir-model-r4bFHIR R4B model, package dev.ohs.fhir.model.r4b
fhir-model-r5FHIR R5 model, package dev.ohs.fhir.model.r5
fhir-modelUmbrella artifact that includes all three

Depend on the single FHIR version you use. The umbrella exists for tools that genuinely handle multiple versions.

What it is not​

  • Not a validator. Constraints, profiles, and binding strengths from StructureDefinitions are not represented in the generated code. Bindings only influence which enums exist.
  • Not a client or a database. There is no networking and no persistence. That is Kotlin FHIR Engine's job.
  • JSON only. XML and Turtle are out of scope. Other kotlinx.serialization formats may work mechanically, but only JSON is extensively tested.
  • Selective generation. Logical models, profiles, CapabilityStatements, CodeSystems, ConceptMaps, NamingSystems, OperationDefinitions, and ValueSets-as-resources are not generated. The abstract FHIR patterns (Event, Request, Definition) are not modeled as interfaces, because conforming resources may rename elements in ways Kotlin inheritance cannot express.
  • Not every search parameter is extractable. Parameters whose FHIRPath patterns the generator does not support throw NotImplementedError. See Extract search parameters.

Next step​

Add the dependency and create your first resource.