FHIR Terminology Service: OMOP Vocabularies for HAPI, EHRbase, and Spring FHIR Clients
Standards-compliant FHIR R4/R5/R6 terminology service over OMOP vocabularies. Point HAPI, EHRbase, or Spring FHIR clients at OMOPHub for $lookup, $validate-code, $translate, and $expand.
We're launching the OMOPHub FHIR Terminology Service: a standards-compliant FHIR R4/R4B/R5/R6 terminology server at https://fhir.omophub.com/fhir/{version}/, exposing the same 130+ OMOP vocabularies our REST API serves but speaking native FHIR. Point HAPI FHIR, EHRbase, Firely, or any Spring-based FHIR stack at it and you get $lookup, $validate-code, $translate, $expand, $subsumes, and ValueSet operations over real OMOP concepts - no SNOMED/RxNorm/LOINC ingest, no terminology server to maintain. This is a terminology service only (CodeSystem, ConceptMap, ValueSet); keep your existing FHIR server for clinical resources and route its terminology calls here.
Available Operations
| Operation | Path | Description |
|---|---|---|
| Metadata | GET /fhir/{version}/metadata | CapabilityStatement describing server capabilities |
| CodeSystem search | GET /fhir/{version}/CodeSystem?url={uri} | Discover support for a canonical system URI; omit url to list all supported CodeSystems |
| CodeSystem read | GET /fhir/{version}/CodeSystem/{id} | Fetch a single CodeSystem by FHIR id |
$lookup | GET|POST /fhir/{version}/CodeSystem/$lookup | Concept details by code |
$validate-code | GET|POST /fhir/{version}/CodeSystem/$validate-code | Check if a code is valid in a CodeSystem |
$translate | GET|POST /fhir/{version}/ConceptMap/$translate | Translate between vocabularies |
$expand | GET|POST /fhir/{version}/ValueSet/$expand | Expand a ValueSet to list matching codes |
| ValueSet search | GET /fhir/{version}/ValueSet?url={uri} | Preflight check for ValueSet support |
ValueSet $validate-code | GET|POST /fhir/{version}/ValueSet/$validate-code | Check if a code is a member of a ValueSet |
$subsumes | GET|POST /fhir/{version}/CodeSystem/$subsumes | Test subsumption between concepts |
$find-matches | GET|POST /fhir/{version}/CodeSystem/$find-matches | Find concepts by property criteria |
$closure | POST /fhir/{version}/ConceptMap/$closure | Compute subsumption closure for a concept set |
| Batch | POST /fhir/{version}/ | Execute multiple GET operations in one request |
$diff (OMOPHub extension) | GET|POST /fhir/{version}/CodeSystem/$diff | Compare concepts between vocabulary versions |
Errors on any /fhir/* path return as FHIR OperationOutcome resources, never as REST JSON envelopes. Both application/fhir+json and application/fhir+xml are supported via standard content negotiation.
FHIR Versions
All four FHIR versions are served from the same endpoint:
/fhir/r4/- FHIR R4 (4.0.1) - US Cures Act, EHDS mandate/fhir/r4b/- FHIR R4B (4.3.0)/fhir/r5/- FHIR R5 (5.0.0)/fhir/r6/- FHIR R6 (6.0.0)/fhir/- defaults to R4
Resource shapes follow the spec for the requested version, so a HAPI R4 client and a Firely R5 client see the same data with the appropriate per-version structure.
Supported Clients
The service works with any FHIR-compatible terminology client. We've explicitly tested and integration-guided the most common ones:
| Client | Auth | Notes |
|---|---|---|
| HAPI FHIR (Java) | OAuth2 client_credentials shim or static bearer | Configure tx-server.url to https://fhir.omophub.com/fhir/r4. Walkthrough in the HAPI FHIR integration guide |
| EHRbase / openEHR | OAuth2 client_credentials shim | Same OAuth2 path as HAPI; the token endpoint accepts both client_secret_basic and client_secret_post |
| Firely (.NET) | Bearer token | Pass the API key directly in Authorization: Bearer ... |
| Any FHIR client | Bearer token | Anything that speaks application/fhir+json works |
Spring-based clients (HAPI JPA Starter, EHRbase, most Java/Kotlin Spring Boot stacks) require an OAuth2 token endpoint to obtain a Bearer token. We expose a minimal RFC 6749 client_credentials shim at https://fhir.omophub.com/oauth2/token that echoes your API key back as the access_token - so existing Spring config templates work without modification.
Quick Start
Confirm the endpoint is reachable and inspect the CapabilityStatement:
curl "https://fhir.omophub.com/fhir/r4/metadata" \
-H "Authorization: Bearer YOUR_API_KEY"
Look up a SNOMED code - the canonical first call any FHIR client makes:
curl "https://fhir.omophub.com/fhir/r4/CodeSystem/\$lookup?\
system=http://snomed.info/sct&code=44054006" \
-H "Authorization: Bearer YOUR_API_KEY"
Translate between vocabularies via ConceptMap/$translate:
curl "https://fhir.omophub.com/fhir/r4/ConceptMap/\$translate?\
system=http://hl7.org/fhir/sid/icd-10-cm&code=E11.9&\
targetsystem=http://snomed.info/sct" \
-H "Authorization: Bearer YOUR_API_KEY"
Each $translate match includes a target-table product property naming the OMOP CDM destination table (condition_occurrence, drug_exposure, measurement, ...) - one less domain lookup for your ETL pipeline.
OMOPHub Extensions
Three operations and properties are OMOPHub-specific, layered on top of the spec:
$diff-GET\|POST /fhir/{version}/CodeSystem/$diffreturns the concept-level diff between two vocabulary releases. Useful for pinning ETL pipelines to a known release and surfacing what changed when you upgrade.- Phoebe recommendations - call
$lookup?property=recommendedto get clinically-related concept recommendations from OMOPHub's Phoebe concept-set engine. Returns concepts that frequently co-occur in published phenotypes alongside the concept you looked up. target-tableon$translate- every$translatematch response carries the OMOP CDM destination table as a product property. Saves a separate domain lookup when building OMOP records from FHIR resources.