kotlin-fhirpath

1.0.0-beta03indexed

Implementation of HL7 FHIRPath with ANTLR-generated parser, strict timezone-aware datetime semantics, UCUM unit support, codegen helpers, validation, conversion, comparison, and conformance-tested evaluator.

AndroidJSJVMNativeWasm·ohs-foundation/kotlin-fhirpath

Stars

Used by

dependents

Health

/ 100

Kotlin FHIRPath

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

Key features

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 units

FHIRPath version support

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.

FHIR version support

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

Supported platforms

The library supports the following target platforms:

The library also supports the following Kotlin/Native targets:

Implementation

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
    A[formal FHIRPath grammar] -- ANTLR Kotlin --> B(lexer, parser, visitor)
    C(Kotlin FHIR data model<br>dev.ohs.fhir:fhir-model)
    subgraph buildSrc
        direction LRTB
        D[FHIR spec<br>in JSON] -- kotlinx.serialization --> E(instances of<br>StructureDefinition<br>Kotlin data class<br>)
        E -- KotlinPoet --> F(generated data model helper functions)
        G[ucum-essence.xml] --> H(generated UCUM helper functions)

    end
    B --> I(FHIRPath Evaluator)
    C --> I
    F --> I
    H --> I

Figure 1: Architecture diagram

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

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.

Timezone offset in date time values

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.

Date time values without timezone offset

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 prioritise 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

@2025-01-01T00:00:+: = ::  
::+: ~ ::  
::+: > ::

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

Date time values with timezone offsets but different precisions

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 {}

Error handling

The FHIRPath specification does not specify the desired behavior when type checking errors occur, allowing the implementation to adopt a strict (e.g. throws an exception) or a lenient (e.g. returns an empty collection) approach. However, the official test suite include test cases that require lenient type checking. To accommodate such cases, this implementation returns an empty collection when the FHIRPath expression attempts to access a data element that does not exist.

Conformance

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.

User Guide

Adding the library dependency to your project

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()
}

Next, follow the instructions for your specific project type.

Kotlin Multiplatform Projects

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 {
            implementation("dev.ohs.fhir:fhir-path:1.0.0-beta03")
        }
    }
}

Android projects

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

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

Evaluating FHIRPath expressions

To evaluate a FHIRPath expression, create a FhirPathEngine for the correct FHIR version and use evaluateExpression function:

import dev.ohs.fhir.fhirpath.FhirPathEngine
import dev.ohs.fhir.model.r4.FhirR4Json

val patientExampleJson = ... // Load "patient-example.json"
val patient = FhirR4Json().decodeFromString(patientExampleJson)
val fhirPathEngine = FhirPathEngine.forR4()
val results = fhirPathEngine.evaluateExpression("name.given", patient)  // ["Peter", "James", "Jim", "Peter", "James"]

Developer Guide

ANTLR

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

./gradlew generateKotlinGrammarSource

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

Model extensions

To run the model extension codegen in buildSrc locally:

./gradlew generateR4Helpers
./gradlew generateR4BHelpers
./gradlew generateR5Helpers

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

UCUM helpers

To run the UCUM helper codegen in buildSrc locally:

./gradlew generateUcumHelpers

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

Dependencies

Dependencies must be kept in sync between the buildSrc/build.gradle.kts file and the gradle/libs.versions.toml file. The former cannot use the latter since the buildSrc directory is precompiled separately in Gradle.

Tests

XmlUtil is used to load the XML test cases from the third_party directory. To run the tests:

./gradlew :fhir-path:jvmTest

The number of passing test cases is displayed on a badge at the top of this page.

Publishing

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.

Maven Local

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

./gradlew :fhir-path:publishToMavenLocal

Maven Central

Publishing to Maven Central requires two sets of credentials:

Maven Central credentials: your Sonatype portal username and password tokens.
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.

Publishing to Maven Central manually

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

Publishing to Maven Central using GitHub Actions

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:

Third Party

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

Early versions of this library (up to 1.0.0-beta01) were published under the group ID com.google.fhir on Google Maven. ↩

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

JsonPathKt★ 64

eygraberEfficiently extracts values from JSON objects using simplified JsonPath syntax. Supports functional programming aspects and avoids exceptions, enhancing performance by up to 7x compared to other implementations.Shared: web, parsing, kotlin-serialization

json-schema-validator★ 64

OptimumCodeValidates JSON elements against various JSON schema drafts, supporting a range of keywords and conditions, including types, enums, patterns, and logical operations. Facilitates schema loading, validation, and error handling.Shared: wasm, validation, kotlin-serialization

kotlin-fhir★ 63

ohs-foundationLean, fast HL7 FHIR data-model implementation with minimal generated classes, JSON-only serialization, multi-version support, and a tiny runtime footprint for efficient healthcare data handling.Shared: web, wasm, kotlin-native

GRPC-Kotlin-Multiplatform★ 133

TimOrtelImplements client-side gRPC with support for parsing proto3 files, generating corresponding code, and suspending RPC calls. Features a DSL for creating proto objects and supports various proto types.Shared: web, wasm, kotlin-native

kotlin.document.store★ 44

lamba92Fast NoSql document store for managing JSON objects with typed and schemaless data. Features developer-friendly APIs, asynchronous operations, indexing, and extensibility for custom serializers or storage backends.Shared: web, kotlin-serialization, kotlin-native

snakeyaml-engine-kmp★ 42

krzema12Processes YAML 1.2 with fine-grained control and advanced functionality. Suitable for projects needing customization and flexibility. Integrates with various platforms and uses comprehensive YAML test suites for validation.Shared: web, wasm, parsing

Early versions of this library (up to 1.0.0-beta01) were published under the group ID com.google.fhir on Google Maven. ↩

Kotlin/JVM	`jvm`	`-jvm`	✅
Kotlin/Wasm	`wasmJs`	`-wasm-js`	✅
Kotlin/Wasm	`wasmWasi`	`-wasm-wasi`	✅
Kotlin/JS	`js`	`-js`	✅
Android applications and libraries	`android`	`-android`	✅

iosSimulatorArm64	`-iossimulatorarm64`	1	✅
iosArm64	`-iosarm64`	1	✅
iosX64	`-iosx64`	3	✅

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

`testPolymorphismAsB`	Test		To be raised	No error should be thrown according to specification.
`testDateTimeGreaterThanDate1`	Implementation			Comparison of two date time values, one with a timezone offset one without; see Date time values without timezone offset
`testStringIntegerLiteralToQuantity`	Specification/Test			Discussion
`testQuantityLiteralWkToString`	Specification/Test			As above.
`testQuantityLiteralWeekToString`	Specification/Test			As above.
`testQuantity4`	Test		PR
`testSubSetOf3`	Specification/Test			The test resource is invalid and missing (https://github.com/FHIR/fhir-test-cases/issues/247); the scope of "$this" is unclear (https://jira.hl7.org/browse/FHIR-44601)
`testIif11`	Implementation			https://jira.hl7.org/browse/FHIR-44774; https://jira.hl7.org/browse/FHIR-44601
`testEncode*`	Implementation	STU		Function `encode` is not implemented.
`testDecode*`	Implementation	STU		Function `decode` is not implemented.
`testEscape*`	Implementation	STU		Function `escape` is not implemented.
`testUnescape*`	Implementation	STU		Function `unescape` is not implemented.
`testNow1`	Specification/Test			As `testDateTimeGreaterThanDate1`.
`testSort*`	Specification/Test			Function `sort` is not defined in the specification.
`testPlusDate13`	Specification/Test			https://chat.fhir.org/#narrow/channel/179266-fhirpath/topic/Definite.20durations.20above.20seconds.20in.20date.20time.20arithmetic/with/564095766
`testPlusDate15`	Specification/Test			As above.
`testPlusDate18`	Implementation			To be fixed together with `testPlusDate13`, `testPlusDate15`, `testPlusDate21`, `testPlusDate22` for a consistent implementation.
`testPlusDate19`	Implementation			To be fixed together with `testPlusDate13`, `testPlusDate15`, `testPlusDate21`, `testPlusDate22` for a consistent implementation.
`testPlusDate20`	Implementation			To be fixed together with `testPlusDate13`, `testPlusDate15`, `testPlusDate21`, `testPlusDate22` for a consistent implementation.
`testPlusDate21`	Specification/Test			As `testPlusDate13`.
`testPlusDate22`	Specification/Test			As `testPlusDate13`.
`testMinus5`	Specification/Test			As `testPlusDate13`.
`testVariables*`	Implementation			Variables are not implemented.
`testExtension*`	Implementation			Function `extension` is not implemented.
`testType*`	Implementation			Function `type` is not implemented.
`testConformsTo*`	Implementation			Function `conformsTo` is not implemented.
`LowBoundary*`	Implementation	STU		Function `lowBoundary` is not implemented.
`HighBoundary*`	Implementation	STU		Function `highBoundary` is not implemented.
`Comparable*`	Implementation			Function `comparable` is not implemented.
`Precision*`	Implementation			Function `precision` is not implemented.
`testIndex`	Implementation			`$index` is not implemented.
`testPeriodInvariantOld`	Implementation			Function `hasValue` is not implemented.
`testPeriodInvariantNew`	Implementation			Function `lowBoundary` and function `highBoundary` are not implemented.
`testFHIRPathIsFunction*`	Implementation
`testFHIRPathAsFunction*`	Implementation
`testContainedId`	Implementation
`testCombine2`	Implementation			FHIR String and Kotlin String comparison issue in `exclude()` function.
`testCombine3`	Implementation			As above.
`testPrimitiveExtensions`	Implementation			Function `hasValue` is not implemented.

`MAVEN_CENTRAL_USERNAME`	Same as `mavenCentralUsername`
`MAVEN_CENTRAL_PASSWORD`	Same as `mavenCentralPassword`
`GPG_KEY_CONTENTS`	Needs to be exported using the command `gpg --armor --export-secret-keys YOUR_KEY_ID`
`SIGNING_PASSWORD`	Same as `signing.password`

kotlin-fhirpath

Kotlin FHIRPath

Key features

FHIRPath version support

FHIR version support

Supported platforms

Implementation

Timezone offset in date time values

Date time values without timezone offset

Date time values with timezone offsets but different precisions

Error handling

Conformance

User Guide

Adding the library dependency to your project

Kotlin Multiplatform Projects

Android projects

Evaluating FHIRPath expressions

Developer Guide

ANTLR

Model extensions

UCUM helpers

Dependencies

Tests

Publishing

Maven Local

Maven Central

Publishing to Maven Central manually

Publishing to Maven Central using GitHub Actions

Third Party

Footnotes

Related libraries

Kotlin FHIRPath

Key features

FHIRPath version support

FHIR version support

Supported platforms

Implementation

Timezone offset in date time values

Date time values without timezone offset

Date time values with timezone offsets but different precisions

Error handling

Conformance

User Guide

Adding the library dependency to your project

Kotlin Multiplatform Projects

Android projects

Evaluating FHIRPath expressions

Developer Guide

ANTLR

Model extensions

UCUM helpers

Dependencies

Tests

Publishing

Maven Local

Maven Central

Publishing to Maven Central manually

Publishing to Maven Central using GitHub Actions

Third Party

Footnotes

Related libraries