Get started with Kotlin FHIRPath

Goal and scope​

Add Kotlin FHIRPath to a project and evaluate expressions against a resource. Examples use R4, and forR4B() and forR5() behave identically over their own models.

Prerequisites​

• A Kotlin project on a supported target platform.
• Resources represented with Kotlin FHIR, because the engine evaluates against those data classes. The dependency below brings the matching model transitively.

Add the dependency​

kotlin {
  sourceSets {
    commonMain.dependencies {
      implementation("dev.ohs.fhir:fhir-path-r4:1.0.0-beta05")
    }
  }
}

For Android-only or JVM-only projects, the same coordinate goes in the ordinary dependencies block. Use the fhir-path aggregate only if you handle several FHIR versions in one codebase.

Evaluate an expression​

import dev.ohs.fhir.fhirpath.FhirPathEngine
import dev.ohs.fhir.fhirpath.forR4

val engine = FhirPathEngine.forR4()

val givenNames = engine.evaluateExpression("name.given", patient)
// e.g. ["Peter", "James", "Jim"]

evaluateExpression takes the expression string, a base object (a resource or any element from the model), and an optional map of external variables.

val results = engine.evaluateExpression(
  "name.where(use = %nameUse).given",
  patient,
  variables = mapOf("nameUse" to "official"),
)

The result is a Collection<Any> of FHIRPath system values, meaning strings, booleans, big decimals, and the engine's own date, time, and quantity types. An empty collection is a normal outcome, not an error.

Strict mode​

By default the engine is lenient. Accessing a property that does not exist on the input yields an empty collection, as the spec's dynamic evaluation model prescribes. While developing and testing expressions, prefer strict mode, which throws an IllegalStateException on undefined property access.

val strictEngine = FhirPathEngine.forR4(strictMode = true)
val results = strictEngine.evaluateExpression("name.given", patient)

Invalid expression syntax fails fast in both modes. The parser rejects the expression with an error rather than evaluating a partial parse.

Concurrency​

An engine instance holds per-evaluation state internally. Create engine instances cheaply where you need them rather than sharing one instance across concurrent evaluations.

Checkpoint​

engine.evaluateExpression("name.given", patient) returns the given names of your patient as strings. An unexpected empty collection usually means a typo in a property name. Rerun the same expression on a strict engine to get an error instead.

Next step​

Evaluation semantics covers how types, dates, and timezones behave.