Kotlin FHIR Data Capture

A Kotlin Multiplatform library for collecting, validating, and processing structured healthcare data using HL7 FHIR Questionnaires.

This is the KMP port of the OHS Foundation android-fhir datacapture library, previously documented at ohs-foundation.github.io/android-fhir. The original library was Android-only; this version targets multiple platforms using Compose Multiplatform.

Supported platforms

The library's support for different target platforms is listed in the following table:

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	✅
iosX64	-iosx64	3	✅

Catalog app

The catalog module is a multiplatform demo application. To run the iOS variant see catalog-iosApp/README.md.

User Guide

Adding the library dependency to your project

To use the Kotlin FHIR Data Capture library in your project, you need to add the library dependency to 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-data-capture:2.0.0-alpha01")
        }
    }
}

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-data-capture:2.0.0-alpha02")
}

Working with Questionnaires

Render a questionnaire using the Questionnaire composable:

Questionnaire(
    questionnaireJson = myQuestionnaireJson,
    questionnaireResponseJson = existingResponseJson, // optional pre-fill
    showSubmitButton = true,
    showCancelButton = true,
    showReviewPage = false,
    isReadOnly = false,
    onSubmit = { getResponse ->
        val response = getResponse()
        // handle QuestionnaireResponse
    },
    onCancel = {
        navController.popBackStack()
    },
)

Developer guide

Testing

Tests are located in the following source sets:

• commonTest: Shared tests (logical validation rules and Compose UI rendering/flows) that run across all targets.
• jvmTest: JVM-specific tests verifying localized date, time, and datetime input parsing/formatting using JVM Locales (java.util.Locale).
• androidDeviceTest: Android-specific instrumentation tests verifying interactions with native Android date, time, and datetime picker dialogs (requires a connected device or emulator).

CI Platform Coverage

The CI pipeline automatically runs checks on every push and pull request. The table below details which test source sets (listed above) are executed by each target's CI task:

Platform	Gradle task	CI runner	Test source sets	Notes
JVM	:datacapture:jvmTest	ubuntu-latest	commonTest, jvmTest	Requires xvfb-run on Linux runners to host virtual framebuffer for Compose tests
Wasm JS (Browser)	:datacapture:wasmJsBrowserTest	ubuntu-latest	commonTest	Runs in headless Chrome
JS (Browser)	:datacapture:jsBrowserTest	ubuntu-latest	commonTest	Runs in headless Chrome
Android	:datacapture:testAndroidHostTest	ubuntu-latest	commonTest	Runs host unit tests on JVM
iOS (Simulator)	:datacapture:iosSimulatorArm64Test	macos-latest	commonTest	Runs in simulator environment

Running Tests Locally

To run all CI-validated test suites locally:

./gradlew check

To run a specific test suite locally, run the corresponding Gradle task:

• JVM: ./gradlew :datacapture:jvmTest
• Wasm: ./gradlew :datacapture:wasmJsBrowserTest
• JS: ./gradlew :datacapture:jsBrowserTest
• Android Host: ./datacapture:testAndroidHostTest
• iOS Simulator: ./gradlew :datacapture:iosSimulatorArm64Test

On-Device Android Tests

The platform-specific Android UI tests (located under androidDeviceTest) are not run automatically on CI. To run them locally:

1. Connect a physical Android device or start an emulator.
2. Execute the connected test task:

   ./gradlew :datacapture:connectedAndroidDeviceTest

Publishing

To publish a new release, first update mavenVersion in gradle.properties to the new version. Then follow one of the methods below:

Maven Local

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

./gradlew :datacapture:publishToMavenLocal

Maven Central

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.

Publishing to Maven Central manually

For manual publishing, store the credentials in the global ~/.gradle/gradle.properties in your environment (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 :datacapture: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 (already set up):

Secret	Description
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

Footnotes

1. Early versions of this library (up to 1.0.0-beta02) were published under the group ID com.google.android.fhir and artifact ID data-capture on Google Maven. ↩