Kotlin FHIRPath is an implementation of HL7® FHIR®'s FHIRPath on Kotlin Multiplatform.

• Strict conformation to the FHIRPath specification, with predictable and well-documented behavior
• Built with an ANTLR-generated parser for adherence to the formal grammar
• Support for validation, conversion, and comparison between compatible UCUM units
• Multiplatform support across Android, iOS, Desktop (JVM), Server-side (JVM), and Web (Wasm/JS)
• Support for FHIR R4, R4B, R5, and future versions
• Tested against the official FHIR test cases to guarantee correctness

The implementation is based on the FHIRPath Normative Release. However, we also incorporate some of the latest features and clarifications from the Continuous Build wherever feasible. Please note the experimental nature of the sections marked as STU (Standard for Trial Use) in the Continuous Build.

The library supports FHIR R4, R4B and R5. Support will be added for future FHIR versions.

The library supports the following target platforms:

The library also supports the following Kotlin/Native targets:

View Target Platform Artifact Matrix

Each library artifact is published with platform-specific variants. The table below shows the Maven Central release status for every artifact–platform combination:

Platform	fhir-path-core	fhir-path-r4	fhir-path-r4b	fhir-path-r5	fhir-path (R4 + R4B + R5)
Root (KMP)
JVM
Wasm-JS
Wasm-Wasi
JS
Android
iOS Simulator
iOS Device

This project uses ANTLR Kotlin to generate the lexer, parser and visitor directly from the formal FHIRPath grammar. This automated approach ensures correctness, improves maintainability, and significantly reduces development time.

The FHIRPath Evaluator implements the visitor class generated by ANTLR, evaluating FHIRPath expressions by traversing the in-memory data model from the Kotlin FHIR library.

A key requirement for FHIRPath evaluation is the capability to access data elements by name. To achieve this with cross-platform compatibility (avoiding reflection), a codegen embedded in buildSrc generates helper functions to the Kotlin FHIR data model.

graph LR
    subgraph fhir-path-core
        GRAMMAR[formal FHIRPath grammar] -- ANTLR Kotlin --> VISITOR(lexer, parser, visitor)
        VISITOR --> EV(FHIRPath Evaluator)

        UE[ucum-essence.xml] -- buildSrc codegen --> UH(generated UCUM<br>helper functions)
        UH --> EV

        IMPL(implementation of FHIRPath functions) --> EV
    end

    subgraph fhir-path
      subgraph fhir-path-r5
          EV --> FPE5(FhirPathEngine.forR5)
          
          FM5(fhir-model-r5) --> FPE5

          SPEC5[FHIR R5 spec in JSON] -- kotlinx.serialization --> SD5(StructureDefinition<br>data class instances)
          SD5 -- KotlinPoet --> H5(generated R5 helper functions)
          H5 --> FPE5
      end
  
      subgraph fhir-path-r4b
          EV --> FPE4B(FhirPathEngine.forR4B)

          FM4B(fhir-model-r4b) --> FPE4B

          SPEC4B[FHIR R4B spec in JSON] -- kotlinx.serialization --> SD4B(StructureDefinition<br>data class instances)
          SD4B -- KotlinPoet --> H4B(generated R4B helper functions)
          H4B --> FPE4B
      end

      subgraph fhir-path-r4
          EV --> FPE4(FhirPathEngine.forR4)

          FM4(fhir-model-r4) --> FPE4

          SPEC4[FHIR R4 spec in JSON] -- kotlinx.serialization --> SD4(StructureDefinition<br>data class instances)
          SD4 -- KotlinPoet --> H4(generated R4 helper functions)
          H4 --> FPE4
      end
    end

Figure 1: Architecture diagram

The following table lists the chosen internal types for the FHIRPath primitive types.

FHIRPath type	Internal type
Boolean	kotlin.Boolean
String	kotlin.String
Integer	kotlin.Int
Long	kotlin.Long
Decimal	com.ionspin.kotlin.bignum.decimal.BigDecimal
Date	FhirPathDate
DateTime	FhirPathDateTime
Time	FhirPathTime
Quantity	FhirPathQuantity

This project defines Date, DateTime, Time, and Quantity classes in order to implement the FHIRPath specification across different FHIR versions. In particular, DateTime and Time in FHIRPath may include partial time (e.g. missing minutes and seconds), which is not allowed in FHIR. Therefore, new implementations are needed.

To preserve metadata properties such as id and extension, FHIR primitive types are kept intact during expression evaluation for as long as possible, rather than being converted to their corresponding FHIRPath system types.

However, certain operations require this conversion so that elements can be compared by their underlying values. For example, when comparing a FHIR string (FHIR.string) with a FHIRPath string literal (System.string), the primitive string value must be extracted from the FHIR object.

To balance these two requirements, such conversions are performed last-minute only. The operations that trigger conversion include equality (=), comparison (<, <=, >, >=), membership (in, contains), and set functions (union, distinct, intersect, exclude, subsetOf, supersetOf).

This FHIRPath implementation adopts a strict, safety-first approach to date time comparisons, especially around the handling of timezones and date time values with different precisions.

The FHIRPath specification allows implementations to provide a default timezone offset for date time values that do not have one. See the relevant sections on equality, equivalence, and comparison.

To prioritize safety and correctness, when comparing date time values without a timezone offset with date time values with a timezone offset, this implementation does not assume a default timezone offset (such as UTC or the system's timezone offset). This is because the data could have originated from a different system or context unknown to this implementation, making any "guess" potentially incorrect and unsafe.

This leads to the following behavior:

• Equality (=, !=) and comparison (<=, <, >, >=) operators will return an empty result {} to indicate uncertainty
• Equivalence (~) operator will return false since equivalence cannot be proven. Likewise, !~ will return true.

@2025-01-01T00:00:00.0+00:00 = @2025-01-01T00:00:00.0  // returns {} 
@2025-01-01T00:00:00.0+00:00 ~ @2025-01-01T00:00:00.0  // returns false
@2025-01-01T00:00:00.0+00:00 > @2025-01-01T00:00:00.0  // returns {}

[!NOTE] While comparing two date time values without timezone offset, the implementation will treat them as if they had the same timezone offset. This compromise is made so that local date time values can be compared:

@2025-01-01T00:00:00.0 = @2025-01-01T00:00:00.0`  // returns true

According to the specification, two date time values should be compared at each precision, starting from years all the way to seconds. However, this becomes problematic when the date time values at hourly precision have half-hour or quarter-hour timezone offsets. Consider @2025-01-01T00+05:30 and @2025-01-01T00+05:45. In no timezone can both values still be represented as partial date time values at the same precision in order to carry out the comparison algorithm.

Whilst it is possible to implement precision based timing in CQL using intervals, it is not part of the FHIRPath specification. For simplicity, this implementation returns an empty result for comparing partial date time values with timezone offsets.

// Indian Standard Time (IST) and Nepal Time (NPT)
@2025-01-01T00+05:30 = @2025-01-01T00+05:45   // returns {}

This library supports the following precision values for date/time types:

• Date: 4 (year), 6 (month), and 8 (day).
• DateTime: 4 (year), 6 (month), 8 (day), 10 (hour), 12 (minute), 14 (second), and any integer > 14 (fractional seconds with precision - 14 decimal places, e.g., 15 for 1 decimal place, 16 for 2 decimal places, or 17 for millisecond precision).
• Time: 2 (hour), 4 (minute), 6 (second), and any integer > 6 (similarly, fractional seconds with precision - 6 decimal places, e.g., 7 for 1 decimal place, 8 for 2 decimal places, or 9 for millisecond precision).

These values are returned by the precision() function. They are also accepted as inputs to functions that take an optional precision parameter, such as lowBoundary() or highBoundary(). When a precision parameter $N$ is supplied, lowBoundary(N) and highBoundary(N) compute the lowest or highest boundary value of the input's uncertainty interval, rounding and formatting the result to $N$ decimal places (for Decimals) or to the target date/time precision $N$.

Any other values are invalid precision values and will throw an error if passed to such functions.

[!NOTE] The FHIRPath specification treats second and sub-second precisions as a single SECOND precision for equality (=, !=), equivalence (~, !~), and comparison (<, <=, >, >=), using decimal comparison semantics for fractional seconds.

Whilst this library does not perform compile-time type checking discussed in the specification, it supports two run-time property access modes:

• Lenient mode (default): Returns an empty collection ({}) when accessing an undefined property.
• Strict mode: Throws an IllegalStateException when accessing an undefined property.

Test failures against the official FHIR test cases are documented in the table below.

The root cause column documents if the test failure is caused by implementation issues in this repository, if the test cases themselves are problematic, or it is believed that the specification itself is ambiguous or inconsistent. For issues in the test cases and the specification, discussions and proposals should be linked in the table above.

To use Kotlin FHIRPath, add it to the dependencies in your project. To do that, first make sure to include the mavenCentral()¹ repository in the build.gradle.kts file in your project root.

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

Then pick the right artifact along two axes:

1. FHIR version — depend on only the version(s) you need: fhir-path-r4, fhir-path-r4b, fhir-path-r5, or fhir-path for all supported versions.
2. Target platform — choose the setup that matches your project type (see sections below).

For Kotlin Multiplatform projects, add the dependency to the shared commonMain source set within the kotlin block of the module's build.gradle.kts file (e.g., composeApp/build.gradle.kts or shared/build.gradle.kts). This makes the library available across all platforms in your project.

// 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-path-r4:1.0.0-beta04")

            // Or include all versions at once:
            // implementation("dev.ohs.fhir:fhir-path:1.0.0-beta04")
        }
    }
}

For Android projects, add the dependency to the dependencies block in the module's build.gradle.kts file (e.g., app/build.gradle.kts).

// e.g., app/build.gradle.kts
dependencies {
    // Use only the FHIR version(s) you need:
    implementation("dev.ohs.fhir:fhir-path-r4:1.0.0-beta04")

    // Or include all versions at once:
    // implementation("dev.ohs.fhir:fhir-path:1.0.0-beta04")
}

Create a FhirPathEngine for the FHIR version you are working with (R4, R4B, or R5):

// Create an engine for FHIR R4
val fhirPathEngine = FhirPathEngine.forR4()

// Create an engine with strict mode enabled (throws on invalid property access)
val fhirPathEngineStrict = FhirPathEngine.forR4(strictMode = true)

Use evaluateExpression API to evaluate FHIRPath expressions against a FHIR resource:

import dev.ohs.fhir.fhirpath.FhirPathEngine
import dev.ohs.fhir.model.r4.Patient
import kotlinx.serialization.json.Json

val patientExampleJson = ... // Load "patient-example.json"
val json = Json { ignoreUnknownKeys = true }
val patient = json.decodeFromString<Patient>(patientExampleJson)

val fhirPathEngine = FhirPathEngine.forR4()
val results = fhirPathEngine.evaluateExpression("name.given", patient)
// ["Peter", "James", "Jim", "Peter", "James"]

// In strict mode, accessing an unrecognized property throws an IllegalStateException
val fhirPathEngineStrict = FhirPathEngine.forR4(strictMode = true)
strictEngine.evaluateExpression("name.given1", patient) // Throws IllegalStateException

To generate the lexer, parser, and visitor locally using ANTLR Kotlin:

./gradlew :fhir-path-core:generateKotlinGrammarSource

The generated code will be placed in fhir-path-core/build/generated/grammar under package dev.ohs.fhir.fhirpath.parsers.

To generate UCUM helpers:

./gradlew :fhir-path-core:generateUcumHelpers

The generated code will be located in fhir-path-core/build/generated/ucum under package dev.ohs.fhir.fhirpath.ucum.

To generate FHIR version specific model extensions:

./gradlew :fhir-path-r4:generateR4Helpers
./gradlew :fhir-path-r4b:generateR4BHelpers
./gradlew :fhir-path-r5:generateR5Helpers

The generated code will be located in fhir-path-<version>/build/generated under packages dev.ohs.fhir.model.<FHIR_VERSION>.ext and dev.ohs.fhir.fhirpath.

This project distinguishes between two types of tests:

• Spec-based tests: Driven by FhirPathEngineTest.kt, these load the official test cases from third_party/fhir-test-cases/. As they require local file access, they only run on JVM and Android targets. On other platform targets, file loading is stubbed out.
• Unit tests: Located in fhir-path/src/commonTest/kotlin/dev/ohs/fhir/fhirpath/, these verify specific, platform-agnostic behaviors and run across all targets:
  • AggregateTest.kt: Tests nested aggregates.
  • EnvironmentVariablesTest.kt: Tests user-defined external variables.
  • TraceTest.kt: Verifies the logging output of the trace() function.

The CI pipeline runs tests across six platform targets on every push and pull request. To run these tests locally, execute the corresponding Gradle task prefixed with :fhir-path: (e.g., ./gradlew :fhir-path:jvmTest).

[!NOTE] Only the debug Android build variant is tested because debug and release produce identical Kotlin library output.

Publishing is handled by the gradle-maven-publish-plugin. The following sections outline the additional setup required for a developer to publish to Maven Local and Maven Central.

To publish artifacts to your local Maven repository (~/.m2/repository) for local development and testing, run:

./gradlew :fhir-path:publishToMavenLocal

Publishing to Maven Central requires two sets of credentials:

1. Maven Central credentials: your Sonatype portal username and password tokens.
2. GPG signing: a GPG key and its passphrase, used to sign all published artifacts.

See the Kotlin Multiplatform Publishing Guide and the Maven Central Publishing Guide for more information on how to set up these credentials.

For manual publishing, store the credentials in the global ~/.gradle/gradle.properties (not the project's gradle.properties) so they are never committed to the repository:

# Maven Central Credentials
mavenCentralUsername=YOUR_USERNAME_TOKEN
mavenCentralPassword=YOUR_PASSWORD_TOKEN

# GPG Signing (file-based)
signing.keyId=YOUR_KEY_ID
signing.password=YOUR_KEY_PASSWORD
signing.secretKeyRingFile=/path/to/secring.gpg

Then run:

./gradlew :fhir-path:publishToMavenCentral

The project includes a GitHub Actions workflow that publishes to Maven Central when a new GitHub release (or pre-release) is created.

The workflow requires the following GitHub organization or repository secrets:

The third_party directory includes resources from the FHIRPath specification and related repositories for code generation and testing purposes:

• fhir-test-cases: content from the fhir-test-cases repo
  • tests-fhir-r4.xml: R4 test cases (commit)
  • resources JSON versions of the relevant test resources generated using Anton V.'s FHIR Converter alongside the XML versions (commit). The XML and JSON resource files in the fhir-test-cases repository are inconsistent; we use XML files converted to JSON.
• fhirpath-2.0.0: the formal antlr grammar from the FHIRPath Normative Release N1 (v2.0.0) including
• hl7.fhir.r4.core: content from FHIR R4 for code generation
• hl7.fhir.r4b.core: content from FHIR R4B for code generation
• hl7.fhir.r5.core: content from FHIR R5 for code generation
• ucum: content from the UCUM repo