Message Validation

Built-in Validation

HAPI provides a validation framework that checks messages against HL7 specifications during parsing. The ValidationContextFactory creates validation contexts with different strictness levels. When validation is enabled, the parser will throw exceptions for messages that violate structural rules such as missing required segments or invalid field data types. This immediate feedback helps catch integration issues early in development.

import ca.uhn.hl7v2.DefaultHapiContext;
import ca.uhn.hl7v2.HapiContext;
import ca.uhn.hl7v2.model.Message;
import ca.uhn.hl7v2.parser.Parser;
import ca.uhn.hl7v2.validation.ValidationContext;
import ca.uhn.hl7v2.validation.impl.DefaultValidation;
import ca.uhn.hl7v2.validation.impl.ValidationContextFactory;

public class ValidationExample {

    public static void main(String[] args) {
        String hl7Message =
            "MSH|^~\\&|SENDING_APP|SENDING_FACILITY|RECEIVING_APP|RECEIVING_FACILITY|20231117120000||ADT^A01|MSG00001|P|2.5\r" +
            "PID|1||123456^^^HOSPITAL^MR||DOE^JOHN^A||19800115|M\r";

        try {
            HapiContext context = new DefaultHapiContext();

            // Enable validation
            ValidationContext validationContext =
                ValidationContextFactory.defaultValidation();
            context.setValidationContext(validationContext);

            Parser parser = context.getPipeParser();

            // This will validate during parsing
            Message message = parser.parse(hl7Message);

            System.out.println("Message validated successfully!");
            System.out.println("Message type: " + message.getName());

            context.close();

        } catch (Exception e) {
            System.err.println("Validation error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Custom Validation Rules

Beyond built-in validation, you can define custom rules specific to your organization’s requirements. The ValidationRuleBuilder provides a fluent API for targeting specific message versions and types. Common custom validations include requiring specific fields that the HL7 standard marks as optional, enforcing naming conventions, or validating code values against your facility’s master tables. Custom rules execute during parsing alongside built-in validation.

import ca.uhn.hl7v2.DefaultHapiContext;
import ca.uhn.hl7v2.HapiContext;
import ca.uhn.hl7v2.model.Message;
import ca.uhn.hl7v2.parser.Parser;
import ca.uhn.hl7v2.validation.*;
import ca.uhn.hl7v2.validation.impl.DefaultValidation;
import ca.uhn.hl7v2.validation.builder.ValidationRuleBuilder;
import ca.uhn.hl7v2.validation.builder.support.DefaultValidationBuilder;

public class CustomValidationExample {

    public static void main(String[] args) {
        String hl7Message =
            "MSH|^~\\&|SENDING_APP|SENDING_FACILITY|RECEIVING_APP|RECEIVING_FACILITY|20231117120000||ADT^A01|MSG00001|P|2.5\r" +
            "PID|1||123456^^^HOSPITAL^MR||DOE^JOHN^A||19800115|M\r";

        try {
            HapiContext context = new DefaultHapiContext();

            // Create custom validation builder
            ValidationRuleBuilder builder = new DefaultValidationBuilder() {
                @Override
                protected void configure() {
                    super.configure();

                    // Require PID-3 (Patient Identifier)
                    forVersion("2.5")
                        .message("ADT", "A01")
                        .onlyFields("PID-3");

                    // Require PID-5 (Patient Name)
                    forVersion("2.5")
                        .message("ADT", "A01")
                        .onlyFields("PID-5");
                }
            };

            ValidationContext customContext =
                new DefaultValidation(builder.build());
            context.setValidationContext(customContext);

            Parser parser = context.getPipeParser();
            Message message = parser.parse(hl7Message);

            System.out.println("Custom validation passed!");

            context.close();

        } catch (Exception e) {
            System.err.println("Validation error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}