Although DSTU3 has not yet been balloted and finalized by HL7, there are several proposed changes which have been incorporated into the current Continuous Integration Builds of the FHIR specification itself and many of these changes are used as a part of testing scenarios in FHIR Connectathons.

HAPI has support for DSTU3 definitions, based on the snapshot of the resource definitions available at the time that a given version of HAPI is released. These structures are found in the hapi-fhir-structures-dstu3-[version].jar library, with the associated Schemas, ValueSets, and other textual resources being found in hapi-fhir-validation-resources-dstu3-[version].jar. For information on where to find these libraries, see the Download page.

Migrating to DSTU3 does require some effort, as the resource definitions have been migrated to use the "Reference Implementation" structures. These are the resource definitions supplied by HL7, meaning that the process to merge these two libraries has now begun.

The RI Data Model

Since the early days of the FHIR project, there have been two parallel Java implementations of the FHIR Specification: HAPI and the Reference Implementation (RI). The two libraries both had separate data models and parsers, but had little overlap in features other than that. HAPI has a server, database, and rich fluent client that the RI did not have. The RI had profile validation, snapshot generation, and a set other of great utilities that HAPI did not have.

Over the last year, we have been working to bring the two projects together, in order to reduce duplication of effort and let all Java users take advantage of the entire set of available tools.

The biggest change to HAPI users coming from this merging is the adoption of the new RI data structure classes. For users of FHIR DSTU2, we provided a parallel set of structures so that users could choose which library to use (hapi-fhir-structures-dstu2 for HAPI structures, or hapi-fhir-structures-hl7org-dstu2 for RI structures). For DSTU3 we will be using the RI structures only, so users will need to migrate to use these.

Using the new RI Structures

The reference implementation (RI) structures have been added as a new maven dependency library called hapi-fhir-structures-dstu3. See the download page for information on the Maven dependencies for this version of the structures.

A new interface has been added which serves as a master interface for all resource classes: org.hl7.fhir.instance.model.api.IBaseResource. All RI resource classes will be in the package org.hl7.fhir.dstu3.model, as shown below.


Datatypes will also be found inthe same package. Unlike HAPI datatype structures, which all end with "Dt", the RI primitive structure names end with "Type" and the RI composite structures have no suffix, as shown below.


Using the DSTU3 Structures in Your Application

Using these structures is similar to using other structures:

// Create a context for DSTU3
FhirContext ctx = FhirContext.forDstu3();

// Working with RI structures is similar to how it works with the HAPI structures
org.hl7.fhir.dstu3.model.Patient patient = new org.hl7.fhir.dstu3.model.Patient();

// Parsing and encoding works the same way too
String encoded = ctx.newJsonParser().encodeResourceToString(patient);

Upgrading Existing Applications to DSTU3 Draft

If you have an existing application built using a version of previous version of HAPI FHIR, there is one change that may affect you. As shown above, a new interface called IBaseResource has been introduced, and the IResource interface extends from it. Many methods in the API which previously returned IResource now return IBaseResource.

For these methods, you may cast the IBaseResource to IResource if you are using DSTU2 structures, or to IAnyResource if you are using DSTU3 structures.

Please post any problems you might encounter trying to upgrade on the Google Group. Chances are if it's happening to you, it's happening to others. We're happy to help.

Code changes in DSTU3 Structrues

The following is a list of things that have changed in the DSTU3 structures which you will need to accomodate in your code as you upgrade:

Package Structure

  • Structures are all found in the org.hl7.fhir.dstu3.model package, instead of the ca.uhn.fhir.model.dstu2.resource, ca.uhn.fhir.model.dstu2.composite, and ca.uhn.fhir.model.dstu2.valueset packages.


  • Primitive Types are renamed from [foo]Dt to [foo]Type, e.g. StringType and DecimalType
  • Composite Types are renamed from [foo]Dt to [foo], e.g. CodeableConcept and HumanName
  • ResourceReferenceDt is renamed to Reference
  • Reference#getReference() returns the reference text, where Reference#getReferenceElement() returns the IdType representing the reference.

Setter Names

  • Names for some component setters/mutators have changed in the new structures. In the old structures if the field type was a primitive (e.g. a string) there would be two setters: setName(String) and setName(StringDt). In the new structures, the setters are called setName(String) and setNameElement(StringType). This is more consistent with the way the getters are named.

Resource Metadata

  • Resource#getId() returns the string ID (e.g.
  • Resource#getIdElement() returns the IdType previously returned by Resource#getId()
  • Resource metadata (e.g. last update time, tags, etc.) lives in a Meta object accessed using Resource#getMeta() instead of using the #getResourceMetadata() hashmap.
  • Resource#getMeta()#getLastUpdate() returns the resource's last update time
  • Resource#getMeta()#getTag() returns the resource's tag list
  • Resource#getMeta()#getProfile() returns the resource's profile list

Contained Resources

  • Resource#getContained() returns the list of contained resources (previously it returned a useless ContainedDt object which held the list of contained resources)

Enums for ValueSets

  • Enums are named [EnumName] instead of [EnumName]Enum. For example, ConditionVerificationStatusEnum is now called ConditionVerificationStatus

Resource/Datatype Components

  • The Java model classes representing sub-elements within a resource now have a longer name reflecting the containing element name and ending in "Component". For example, the Java structure representing the "Bundle.entry" component was called Entry in the HAPI structures but is called BundleEntryComponent in the RI structures.