Data4Life FHIR SDK

HL7 FHIR Models as Kotlin Multiplatform library

Explore the docs »

Report Bug · Request Feature

Table Of Contents

• About The Project
  • Features
  • Built With
• Getting Started
  • Prerequisites
  • Installation
• Usage
  • Serialization
  • Model
• Roadmap
• Changelog
• Versioning
• Contributing
• Copyright and License
• Related Links

About The Project

The Data4Life FHIR SDK is an implementation of the HL7 FHIR Models for Kotlin. It supports encoding/decoding of FHIR data in JSON format.

Features

• Kotlin representation of FHIR resources, elements and primitives

• FHIR code systems are mostly represented as Enums

• Date/Time parsing, validation and (conversion Java Time / NSDate)

• JSON encoding/decoding

Built With

• Kotlin Multiplatform

• Kotlin Serialization

• Kotlin DateTime

• Python FHIR model generator

Getting Started

Instructions how to get software up and running.

Prerequisites

• Android Studio 7.0.2

• Java 11 | Limitations of Java language features and APIs | Desugaring

• Kotlin 1.5.21

• Android 6.0 (API 23) to Android 11.0 (API 30)

Installation

A step by step series of examples that tell you how to get it running.

Consume GitHub Packages

We use GitHub Packages to distribute the SDK. In order to consume our dependencies you need to generate a GitHub Personal Access Token. Please follow the how to authenticate to GitHub Packages.

NOTICE

You need to have read access to this repository and generate a personal access token with repo and read:packages scope.

Token

The token needs to be made available.

1. Add gpr.user = {GitHub username} and gpr.key = {GitHub Personal Access Token} to your global Gradle properties ~/.gradle/gradle.properties

   gpr.user=github-username
   gpr.key=github-token

2. Or add following environment variables PACKAGE_REGISTRY_USERNAME={GitHub username} and PACKAGE_REGISTRY_TOKEN={GitHub Personal Access Token}

Setup Maven Repository

Add the following maven repository configuration to your root build.gradle:

    allprojects {
        repositories {
            ...
            maven {
                url = URI("https://maven.pkg.github.com/d4l-data4life/hc-fhir-sdk-kmp")
                credentials {
                    username = project.findProperty("gpr.user") as String? ?: System.getenv("PACKAGE_REGISTRY_USERNAME")
                    password = project.findProperty("gpr.key") as String? ?: System.getenv("PACKAGE_REGISTRY_TOKEN")
                }
            }
        }
    }

Usage

How to use this SDK.

Serialization

Create an instance of your desired FhirStu3Parser or FhirR4Parser using FhirParserFactory.createStu3Parser() or FhirParserFactory.createR4Parser().

Decoding and Encoding JSON FHIR data is as simple as:

Decode

In case you know the type of FHIR JSON data, you could directly decode it.

val parser = FhirParserFactory.createR4Parser()

val data = parser.fromJson(DomainResource::class, "JSON FHIR data")

Encode

Just pass your FHIR data to the corresponding FHIR parser to encode to JSON format.

val parser = FhirParserFactory.createR4Parser()

val data = DomainResource()

val result = parser.toJson(data)

Model

FHIR Resources and Elements are represented as Kotlin interfaces which are named Fhir + ResourceType` e.g. FhirDocumentReference. While a FhirDocumentReference is implemented by DocumentReference which is a Kotlin data class. So they are equatable, copyable, destructable by default.

val name = HumanName(family = "Doe", given = listOf("John"))
val patient = Patient(name = listOf(name))

val newName = HumanName(family = "Doe", given = listOf("Jane"))
val patientCopy = patient.copy(name = listOf(newName))

If you need to access the FHIR resourceType from a given class or need to get the class for a given FHIR resourceType use the FhirHelper.FhirElementFactory:

val resourceType = FhirHelper.FhirElementFactory.getFhirResourceType(Patient::class)

val clazz = FhirHelper.FhirElementFactory.getFhirClass(resourceType)

Roadmap

This project is work in progress. We are working on adding more functionality, guidelines, documentation and other improvements.

Next planed features:

• add FHIR primitive extension support

• add more FHIR primitives

• add direct decoding from JSON without the need to pass in the correct type

• conversion to and from Java Time / NSDate

• write new FHIR generator

• add FHIR 5 once ready

Also see the open issues for a list of proposed features and known issues.

Changelog

See changelog

Versioning

We use Semantic Versioning as a guideline for our versioning.

Releases use this format: {major}.{minor}.{patch}

• Breaking changes bump {major} and reset {minor} & {patch}

• Backward compatible changes bump {minor} and reset {patch}

• Bug fixes bump {patch}

Contributing

You want to help or share a proposal? You have a specific problem? Read the following:

• Code of conduct for details on our code of conduct.

• Contributing for details about how to report bugs and propose features.

• Developing for details about our development process and how to build and test the project.

Copyright and License

Copyright (c) 2021 D4L data4life gGmbH / All rights reserved.

Please refer to our License for further details.

Related Links

• FHIR current

• FHIR 3 Overview - STU3-3.0.1.zip

• FHIR 4

• Python FHIR model generator