HAPI Structure Library HAPI Version FHIR Specification Version
hapi-fhir-structures-dstu HAPI FHIR 1.1 - 2.1 DSTU1 0.0.82
hapi-fhir-structures-dstu2 HAPI FHIR 1.1 DSTU2 0.5.0
HAPI FHIR 1.2 DSTU2 1.0.0
HAPI FHIR 1.3 - 2.2 DSTU2 1.0.2
hapi-fhir-structures-hl7org-dstu2 HAPI FHIR 1.1 DSTU2 0.5.0 Snapshot (SVN 5843)
HAPI FHIR 1.2 DSTU2 1.0.0
HAPI FHIR 1.3 - 2.2 DSTU2 1.0.2
hapi-fhir-structures-dstu2.1 HAPI FHIR 2.2 DSTU3 1.4.0 Snapshot (May 2016 / Baltimore)
hapi-fhir-structures-dstu3 HAPI FHIR 1.4 STU3 1.3.0 Snapshot (SVN 7602)
HAPI FHIR 1.5 STU3 1.4.0 Snapshot (SVN 8138)
HAPI FHIR 1.6 STU3 1.4.0 Snapshot (SVN 8636)
HAPI FHIR 2.0 STU3 1.6.0 (SVN 9663)
HAPI FHIR 2.1 STU3 1.7.0 (SVN 10129)
HAPI FHIR 2.2 STU3 1.8.0 (SVN 10528)
HAPI FHIR 2.3 STU3 1.9.0 (SVN 11501)

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.

DSTU1 Resources - HAPI Structures

HAPI supports multiple versions of the FHIR specification. Code which needs to interact with or implement the DSTU1 specification (which is now gradually beginning to be replaced by newer specifications) can do so using hapi-fhir-structures-dstu-[version].jar.

If you use Maven, you can include these JARs with the following dependency tags to enable DSTU1 support:

<dependency>
   <groupId>ca.uhn.hapi.fhir</groupId>
   <artifactId>hapi-fhir-base</artifactId>
   <version>2.3</version>
</dependency>
<dependency>
   <groupId>ca.uhn.hapi.fhir</groupId>
   <artifactId>hapi-fhir-structures-dstu</artifactId>
   <version>2.3</version>
</dependency>

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>2.3</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>2.3</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>2.3</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:2.3'
compile 'ca.uhn.hapi.fhir:hapi-fhir-structures-dstu:2.3'

DSTU2 (HAPI):

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

DSTU2 (RI):

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

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");

Phloc-Schematron

If you are using the Schematron Validatioon module, you will also need to include the Phloc library on your classpath.

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.phloc</groupId>
    <artifactId>phloc-schematron</artifactId>
    <version>2.7.1</version>
</dependency>
<dependency>
    <groupId>com.phloc</groupId>
    <artifactId>phloc-commons</artifactId>
    <version>4.4.6</version>
</dependency>

Back to top

Reflow Maven skin by Andrius Velykis.