HAPI includes several tools which may be used to work with Conformance Profiles.

Conformance Class Generator

HAPI 1.1 introduced a new conformance class generator, which takes a conformance profile and generates a HAPI message definition. This is useful both to constrain/remove unwanted elements from a message type, as well as to extend a message type by adding custom segments.

This feature was developed by University Health Network, and is currently being used quite heavily in a production ESB/interface engine to create message structures for translating messages between arbitrary formats. Applications that can produce message with custom Z-segments, out of order segments, and other nuances are no longer an issue.

For a complete reference on how the plugin works, check out the Maven Plugin Documentation

Important: Note that this functionality is still a work in progress, and has the following limitations:

  • Fields which are marked as "not used" are not yet constrained away. As such, this plugin is really currently only useful for extending existing message types, not constraining them. Constraining is the next planned use-case for implementation. Get in touch if you would like to help.
  • The new generator is only provided as a Maven plugin. Converting it to work with Ant or as a standalone application would be fairly easy, please get in touch if you would like to contribute.


First, generate a conformance profile using the Message Workbench tool. This tool will export your profile as an XML file, which can be read by the conformance class generator. Save this file in your project under


Next, add the Maven plugin to your pom:


          <!-- This is the conformance profile file to use -->

          <!-- Place generated Java source here -->

          <!-- Generated classes will be placed here -->


You will now have a "com.foo" package containing your newly generated classes. If you are using eclipse, you might now want to add the following directory to your source path so that you can see the generated sources:


To see an example:

  • View the conformance profile XML file HERE.
  • View the generated source classes HERE.

Runtime Message Validator

The Default Validator accepts a conformance profile and validates a message against it at runtime. Example usage:

// Load the profile from the classpath
ProfileParser parser = new ProfileParser(false);
RuntimeProfile profile = parser.parseClasspath("ca/uhn/hl7v2/conf/parser/example_ack.xml");

// Create a message to validate
String message = "MSH|^~\\&|||||||ACK^A01|1|D|2.4|||||CAN|wrong|F^^HL70001^x^^HL78888|\r"; //note HL7888 doesn't exist
ACK msg = (ACK) (new PipeParser()).parse(message);

// Validate
HL7Exception[] errors = new DefaultValidator().validate(msg, profile.getMessage());

// Each exception is a validation error
System.out.println("Validation errors: " + Arrays.asList(errors));

Older tools

Version 0.4 of HAPI introduces several features related to the HL7 conformance framework. There are also several non-HAPI conformance tools.

The conformance framework was introduced in HL7 2.5. In a nutshell, it defines a way of writing detailed message specifications using XML. An XML message specification is called a "profile". For more information on conformance, please refer to HL7 2.5 section 2.12 or the Conformance SIG.

HAPI 0.4 introduces the following conformance tools:

Profile Compiler Turns a profile into a Java JAR. The JAR contains an API with all the constraints of the profile, so that coding against it will prevent you from producing non-compliant messages. Many non-conformances are caught at compile time, the rest at run-time.
Constraint Analyzer Determines whether one profile properly constrains another.
Profile Store In progress. Currently saves/loads profiles to/from local disk. Will load profiles from HL7's on-line registry and cache them locally in next version.

Non-HAPI Conformance Tools

The Messaging Workbench This is a graphical profile editor created by Peter Rontey of the US Veteran's Administration. It can be downloaded from the HL7 Conformance SIG's documents page.
Message Maker This tool by Rob Snelick and colleagues (NIST) generates test messages from a conformance profile.
PDF Transform Lloyd McKenzie and Jennifer Puyenbroek's XSL stylesheet which transforms a profile into PDF or HTML.
Australian Healthcare Messaging Laboratory A service by which messages can be checked for conformance to a profile or to HL7 in general.
HL7 Global Profile Registry A service with which HL7 members can share profiles for their products or regions. This is a link to the users guide which has instructions for accessing the registry.
Orion Tools Closed-source tools in the same vein as HAPI.

Possible future work includes:

Profile Generator Currently the Messaging Workbench (above) can reverse-engineer a profile from a message. There has been some talk about extending this so that a profile can be created from a set of messages, which would be very useful in that it would allow us to create status quo profiles for legacy interfaces. If Peter doesn't do it, maybe we'll implement this into HAPI at some point.