The HAPI Echidna: High-Performance OMOP Terminology for HAPI FHIR

Guy Tsafnat — Tue, 20 Jan 2026 12:31:22 +0000

HAPI FHIR is the gold standard for open source FHIR servers, but its internal terminology management can be resource-intensive, especially when dealing with massive datasets like SNOMED-CT or LOINC, and maintaining the latest versions of your terminologies can be a massive headache. Echidna (echidna.fhir.org) provides a cloud-native terminology server that bridges the gap between OMOP and FHIR, offering blazing-fast lookups and translations without the overhead of local database maintenance.

Switching to Echidna is super simple and free. Let’s see how to do this.

Prerequisites

A running instance of HAPI FHIR JPA Starter (or a custom HAPI-based server).
Internet access for your server to reach https://echidna.fhir.org.
A basic understanding of the FHIR.

Option 1: Configuration via `application.yaml`

If you are using the HAPI FHIR JPA Starter project, you can switch to Echidna by modifying your configuration file. This is the fastest "no-code" method.

Open your application.yaml file.
Add or modify the following properties:

YAML

hapi:
   fhir:
     # Enable remote terminology validation
     remote_terminology_service_enabled: true

     # Set the Echidna R5 endpoint
     remote_terminology_server_base_url: 'https://echidna.fhir.org/r5'

     # If you have an Echidna membership, you can specify it here:
     # remote_terminology_server_auth_token: 'your-echidna-token-here'

By setting these, HAPI will automatically delegate terminology operations it cannot resolve locally to Echidna.

Option 2: Java Configuration (Custom Implementation)

For developers building a custom HAPI FHIR server using the IValidationSupportchain, you must manually inject the RemoteTerminologyServiceValidationSupportmodule.

Java

// 1. Initialize the FhirContext 
FhirContext ctx = FhirContext.forR5(); 

// 2. Create the Remote Terminology module pointing to Echidna
RemoteTerminologyServiceValidationSupport remoteTermSvc =
      new RemoteTerminologyServiceValidationSupport(ctx);
remoteTermSvc.setBaseUrl("https://echidna.fhir.org/r5"); 

// 3. Add it to your ValidationSupportChain 
ValidationSupportChain chain =
      new ValidationSupportChain(
           new DefaultProfileValidationSupport(ctx),
           new InMemoryTerminologyServerValidationSupport(ctx),
           remoteTermSvc // Delegated to Echidna
      );

With this option, when HAPI encounters a code validation request (e.g., checking if a SNOMED code is valid), it traverses the ValidationSupportChain. By placing the Echidna remote service in this chain, HAPI can leverage Echidna’s vast OMOP-mapped vocabulary library (10M+ concepts) as if they were stored locally.

Done!

Simply restart the server for the changes to take effect. You can verify to see that everything works as promised.

Verifying the setup

You can verify the integration by performing a $lookup operation through your HAPI server that requires Echidna's specialized OMOP-to-FHIR logic.

Example Request:

HTTP

GET http://your-hapi/fhir/CodeSystem/$lookup?\ 
    system=http://fhir-terminology.ohdsi.org&code=49495001

Or, if you are using CURL

Shell

$ curl http://your-hapi/fhir/CodeSystem/$lookup?\ 
       system=http://fhir-terminology.ohdsi.org&code=49495001

If everything is configured correctly, HAPI will forward this request to Echidna and return the concept details (Display: "Leukemia") retrieved from the remote server.