The following table shows the various versions of the HAPI FHIR library, and the versions of the FHIR standard that they support. Note that support for stable releases of FHIR are shown in GREEN and support for draft pre-release versions of FHIR are shown in YELLOW.

Note also that after the release of the FHIR DSTU2 specification, the FHIR standard itself stopped using the DSTUx naming scheme, in favour or naming new releases STUx or simply Rx. Because HAPI FHIR already had draft support for what was then called DSTU3 at this time, we did not update our naming conventions until R4 in order to avoid breaking existing users' code. From the perspective of a user of HAPI FHIR, consider the terms DSTU3 / STU3 / R3 to be interchangeable.

HAPI Version Min JDK DSTU1 DSTU2 DSTU2.1 DSTU3 R4
HAPI FHIR 1.1 JDK6 0.0.82 0.5.0-5843
HAPI FHIR 1.2 JDK6 0.0.82 0.5.0-5843
HAPI FHIR 1.3 JDK6 0.0.82 1.0.2
HAPI FHIR 1.4 JDK6 0.0.82 1.0.2 1.3.0-7602
HAPI FHIR 1.5 JDK6 0.0.82 1.0.2 1.4.0-8138
HAPI FHIR 1.6 JDK6 0.0.82 1.0.2 1.4.0-8636
HAPI FHIR 2.0 JDK6 0.0.82 1.0.2 1.6.0-9663
HAPI FHIR 2.1 JDK6 0.0.82 1.0.2 1.7.0-10129
HAPI FHIR 2.2 JDK6 0.0.82 1.0.2 1.4.0 1.8.0-10528
HAPI FHIR 2.3 JDK6 0.0.82 1.0.2 1.4.0 1.9.0-11501
HAPI FHIR 2.4 JDK6 0.0.82 1.0.2 1.4.0 3.0.1
HAPI FHIR 2.5 JDK6 0.0.82 1.0.2 1.4.0 3.0.1
HAPI FHIR 3.0.0 JDK7 1.0.2 1.4.0 3.0.1 3.1.0-12370
HAPI FHIR 3.1.0 JDK7 1.0.2 1.4.0 3.0.1 3.1.0-12370
HAPI FHIR 3.2.0 JDK7 1.0.2 1.4.0 3.0.1 3.2.0-12917
HAPI FHIR 3.3.0 JDK7 1.0.2 1.4.0 3.0.1 3.2.0-13271
HAPI FHIR 3.4.0 JDK8 1.0.2 1.4.0 3.0.1 3.4.0-13732
HAPI FHIR 3.5.0 JDK8 1.0.2 1.4.0 3.0.1 3.4.0-13732
HAPI FHIR 3.6.0-SNAPSHOT JDK8 1.0.2 1.4.0 3.0.1 3.6.0-1202b2eed0f

HAPI FHIR Modules

The following table shows the modules that make up the HAPI FHIR library.

Core Libraries
hapi-fhir-base This is the core HAPI FHIR library and is always required in order to use the framework. It contains the context, parsers, and other support classes.
hapi-fhir-utilities This is a support library containing various utility methods for working with FHIR. It is always required in order to use the framework.
Structures
hapi-fhir-structures-dstu This module contains FHIR DSTU1 model classes. It was retired in HAPI FHIR 3.0.0.
hapi-fhir-structures-dstu2 This module contains FHIR DSTU2 model classes.
hapi-fhir-structures-hl7org-dstu2 This module contains alternate FHIR DSTU2 model classes. The HAPI FHIR and FHIR "Java Reference Implementation" libraries were merged in 2015, and at the time there were two parallel sets of DSTU2 model classes. This set more closely resembles the model classes for DSTU3+ where the other set more closely resembles the DSTU1 model classes. The two DSTU2 model JARs are functionally identital, but the various utility methods on the classes are somewhat different.
hapi-fhir-structures-dstu3 This module contains FHIR DSTU3 model classes.
hapi-fhir-structures-r4 This module contains FHIR R4 model classes.
Client Framework
hapi-fhir-client This module contains the core FHIR client framework, including an HTTP implementation based on Apache HttpClient. It is required in order to use client functionality in HAPI.
hapi-fhir-client-okhttp This module contains an alternate HTTP implementation based on OKHTTP.
hapi-fhir-android This module contains the Android HAPI FHIR framework, which is a FHIR client framework which has been tailed specifically to run on Android.
Validation
hapi-fhir-validation This module contains the FHIR Profile Validator, which is used to validate resource instances against FHIR Profiles (StructureDefinitions, ValueSets, CodeSystems, etc.).
hapi-fhir-validation-resources-dstu2 This module contains the StructureDefinitions, ValueSets, CodeSystems, Schemas, and Schematrons for FHIR DSTU2
hapi-fhir-validation-resources-dstu2.1 This module contains the StructureDefinitions, ValueSets, CodeSystems, Schemas, and Schematrons for FHIR DSTU2.1
hapi-fhir-validation-resources-dstu3 This module contains the StructureDefinitions, ValueSets, CodeSystems, Schemas, and Schematrons for FHIR DSTU3
hapi-fhir-validation-resources-r4 This module contains the StructureDefinitions, ValueSets, CodeSystems, Schemas, and Schematrons for FHIR R4
Server
hapi-fhir-server This module contains the HAPI FHIR Server framework, which can be used to develop FHIR compliant servers against your own data storage layer.
hapi-fhir-jpaserver-base This module contains the HAPI FHIR "JPA Server", which is a complete FHIR server solution including a database and implementations of many advanced FHIR server features.
hapi-fhir-testpage-overlay This module contains the web based "testpage overlay", which is the UI that powers our Public Demo Server and can also be added to your applications.

Downloading HAPI FHIR

If you are developing applications in Java, the easiest way to use HAPI is to use a build system which handles dependency management automatically. The two most common such systems are Apache Maven and Gradle. These systems will automatically download "dependency" libraries and add them to your classpath. If you are not using one of these systems, you can still manually download the latest release of HAPI by looking in the GitHub Release Section.

Note on "snapshot" (pre-release) builds

FHIR is a fast moving specification, and there is a lot of ongoing work in HAPI as well. While we regularly put out new releases, there may be times when you want to try out the latest unreleased version. You can ususally look at the source of the changes report to get a sense of what has changed in the next unreleased version.

See using snapshot builds below to find out how to get these builds.

Maven Users

To use HAPI in your application, at a minimum you need to include the HAPI-FHIR core JAR hapi-fhir-base-[version].jar, as well as at least one "structures" JAR. The structures JAR contains classes with the resource and datatype definitions for a given version of FHIR.

DSTU2 Resources - HAPI Structures

HAPI also has a hapi-fhir-structures-dstu2-[version].jar, which contains the latest versions of the releases. You can include this JAR on your classpath if you want to use resources that were created or updated by HL7 after the DSTU1 release. Be warned though that using these resources can lead to incompatibility between your application and other applications if those applications are designed to be compliant with FHIR DSTU1.

If you are using Maven, add the following dependency to include DSTU2 resources. Note that if you do not need to support DSTU1 resources, you do not need to include the "hapi-fhir-structures-dstu" artifact.

<dependency>
   <groupId>ca.uhn.hapi.fhir</groupId>
   <artifactId>hapi-fhir-structures-dstu2</artifactId>
   <version>3.6.0</version>
</dependency>

DSTU2 Resources - HL7.org Structures

To use the HL7.org reference implementation structures (see the DSTU2 page for more information), use the following dependency.

<dependency>
   <groupId>ca.uhn.hapi.fhir</groupId>
   <artifactId>hapi-fhir-structures-hl7org-dstu2</artifactId>
   <version>3.6.0</version>
</dependency>

If you want to use HAPI's StructureDefinition validation you will also need to include the hapi-fhir-validation-resources-dstu2-[version].jar:

<dependency>
   <groupId>ca.uhn.hapi.fhir</groupId>
   <artifactId>hapi-fhir-validation-resources-dstu2</artifactId>
   <version>3.6.0</version>
</dependency>

Gradle Users

If you are using Gradle, you may use the following dependencies. Note that if you are doing Android development, you may want to use our Android build instead.

DSTU1:

compile 'ca.uhn.hapi.fhir:hapi-fhir-base:3.6.0'
compile 'ca.uhn.hapi.fhir:hapi-fhir-structures-dstu:3.6.0'

DSTU2 (HAPI):

compile 'ca.uhn.hapi.fhir:hapi-fhir-base:3.6.0'
compile 'ca.uhn.hapi.fhir:hapi-fhir-structures-dstu2:3.6.0'

DSTU2 (RI):

compile 'ca.uhn.hapi.fhir:hapi-fhir-base:3.6.0'
compile 'ca.uhn.hapi.fhir:hapi-fhir-structures-hl7org-dstu2:3.6.0'
compile 'ca.uhn.hapi.fhir:hapi-fhir-validation-resources-dstu2:3.6.0'

Using Snapshot Builds

Snapshot builds of HAPI are pre-release builds which can contain fixes and new features not yet released in a formal release. To use snapshot builds of HAPI you may need to add a reference to the OSS snapshot repository to your project build file.

Using Maven:

<repositories>
   <repository>
      <id>oss-snapshots</id>
      <snapshots>
         <enabled>true</enabled>
      </snapshots>
      <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
   </repository>
</repositories>

Using Gradle:

repositories {
   mavenCentral()
   maven {
      url "https://oss.sonatype.org/content/repositories/snapshots"
   }
}

Dependencies

The HAPI-FHIR library depends on other libraries to provide specific functionality. Some of those libraries are listed here:

Logging (SLF4j, Logback, etc.)

HAPI requires SLF4j for logging support, and it is recommended to include an underlying logging framework such as Logback. See the logging documentation for more information.

StAX / Woodstox

XML processing (for resource marshalling and unmarshalling) uses the Java StAX API, which is a fast and efficient API for XML processing. HAPI bundles (for release archives) and depends on (for Maven builds) the Woodstox library, which is a good implementation of StAX.

Upon starting up, HAPI will emit a log line indicating which StAX implementation is being used, e.g:

08:01:32.044 [main] INFO  ca.uhn.fhir.util.XmlUtil - FHIR XML procesing will use StAX implementation 'Woodstox XML-processor' version '4.4.0'

Although most testing is done using the Woodstox implementation of StAX, it is not required and HAPI should work correctly with any compliant implementation of StAX.

You can force Woodstox in an environment where multiple StAX libraries are present by setting the following system properties:

System.setProperty("javax.xml.stream.XMLInputFactory", "com.ctc.wstx.stax.WstxInputFactory");
System.setProperty("javax.xml.stream.XMLOutputFactory", "com.ctc.wstx.stax.WstxOutputFactory");
System.setProperty("javax.xml.stream.XMLEventFactory", "com.ctc.wstx.stax.WstxEventFactory");

Ph-Schematron

If you are using the Schematron Validatioon module, you will also need to include the Ph-Schematron library on your classpath. (Note that prior to HAPI FHIR 3.4.0 we used Phloc-Schamtron instead, but that lirary has been discontinued)

If you are using Maven, this library is not added by default (it is marked as an optional dependency) since not all applications need Schematron support. As a result you will need to manually add the following dependencies to your project POM.xml

<dependency>
	<groupId>com.helger</groupId>
	<artifactId>ph-schematron</artifactId>
	<version>5.0.4</version>
</dependency>
<dependency>
	<groupId>com.helger</groupId>
	<artifactId>ph-commons</artifactId>
	<version>9.1.1</version>
</dependency>

Back to top

Reflow Maven skin by Andrius Velykis.