Skip to main content

Terminology Service

The WSO2 Healthcare Accelerator includes a pre-built FHIR R4 Terminology Service that provides RESTful APIs for managing and querying FHIR ValueSets, CodeSystems, and ConceptMaps. It is designed to be compatible with the HL7 FHIR Terminology Service specification and supports key terminology operations such as expansion, validation, lookup, subsumption, translation, and closure.

Features​

  • ValueSet Operations -- Expand, validate codes, search, create, and retrieve ValueSets.
  • CodeSystem Operations -- Lookup, validate codes, test subsumption, search, create, and retrieve CodeSystems.
  • ConceptMap Operations -- Translate codes between code systems, search, create, and retrieve ConceptMaps.
  • Closure Table -- Maintain a client-named, incrementally-growing subsumption closure table via $closure.
  • Batch Validation -- Validate multiple ValueSets in a single request.
  • Upload -- Upload terminology content from FHIR resource bundles, or native LOINC, SNOMED CT, and ICD-10-CM release archives in bulk.
  • Find Code -- Search for codes across CodeSystems by display or definition text.
  • FHIR CapabilityStatement -- Exposes service metadata for FHIR clients.

Supported Terminology Types​

The service supports loading and querying the following standard terminology systems:

TerminologyType
SNOMED CTClinical findings, procedures
LOINCLab observations, clinical measurements
ICD-10-CMDiagnoses
FHIRBuilt-in FHIR code systems and value sets

API Endpoints​

All endpoints are served under /fhir/r4:

OperationEndpointDescription
$expandGET/POST /ValueSet/$expandExpand a ValueSet
$validate-codeGET/POST /ValueSet/$validate-codeValidate a code against a ValueSet
$lookupGET/POST /CodeSystem/$lookupLook up a code in a CodeSystem
$validate-codeGET/POST /CodeSystem/$validate-codeValidate a code against a CodeSystem
$subsumesGET/POST /CodeSystem/$subsumesTest subsumption relationships
$translateGET/POST /ConceptMap/$translateTranslate a code using a ConceptMap
$closurePOST /$closureMaintain an incremental subsumption closure table
Search ValueSetsGET /ValueSetSearch ValueSets
Search CodeSystemsGET /CodeSystemSearch CodeSystems
Search ConceptMapsGET /ConceptMapSearch ConceptMaps
Get by IDGET /ValueSet/{id}, GET /CodeSystem/{id}, GET /ConceptMap/{id}Retrieve by ID
CreatePOST /ValueSet, POST /CodeSystem, POST /ConceptMapCreate new resources
Batch ValidatePOST /Batch validate ValueSets
$uploadPOST /%24uploadUpload terminology resources in bulk
$find-codeGET/POST /$find-codeSearch for codes across CodeSystems
$versionsGET/POST /$versionsReport supported FHIR versions
MetadataGET /metadataFHIR CapabilityStatement

Setting Up the Terminology Service​

Prerequisites​

Clone the WSO2 Healthcare Accelerator repository and navigate to the terminology service:

git clone https://github.com/wso2/open-healthcare-choreo-accelerators.git
cd open-healthcare-choreo-accelerators/terminology/terminology-service

Database Configuration​

The terminology service requires a database backend. Two database types are supported:

H2 (Embedded)​

Suitable for development and testing. Configure in Config.toml:

[wso2.terminology_service]
db_type = "h2"

[wso2.terminology_service.store_h2]
url = "jdbc:h2:./resources/database/terminologyDB"
user = "sa"
password = ""

PostgreSQL​

Recommended for production. Configure in Config.toml:

[wso2.terminology_service]
db_type = "postgresql"

[wso2.terminology_service.store_pg]
host = "localhost"
database = "terminology"
user = "dbuser"
password = "dbpassword"
port = 5432

Running the Service​

Start the terminology service:

bal run

The service starts on port 9090 by default and is available at http://localhost:9090/fhir/r4.

Verifying the Service​

Check the service metadata:

curl http://localhost:9090/fhir/r4/metadata

Quick Start​

Validate a Code​

curl 'http://localhost:9090/fhir/r4/ValueSet/snomed-diabetes-example/$validate-code?system=http://snomed.info/sct&code=73211009'

Response:

{
"resourceType": "Parameters",
"parameter": [
{
"name": "result",
"valueBoolean": true
},
{
"valueCode": "73211009",
"name": "code"
},
{
"name": "display",
"valueString": "Diabetes mellitus"
}
]
}

Expand a ValueSet​

curl 'http://localhost:9090/fhir/r4/ValueSet/$expand?url=http://example.org/fhir/ValueSet/snomed-diabetes-example'

Look Up a Code​

curl 'http://localhost:9090/fhir/r4/CodeSystem/$lookup?system=http://loinc.org&code=100011-6'

Translate a Code​

curl 'http://localhost:9090/fhir/r4/ConceptMap/$translate?source=http://snomed.info/sct&target=http://loinc.org&system=http://snomed.info/sct&code=271649006'

Integrating with Terminology Validation​

The pre-built terminology service can be used as the backend for terminology validation in your integrations. Point your Config.toml terminology configuration to the running service:

[ballerinax.health.fhir.r4.parser.terminologyConfig]
isTerminologyValidationEnabled = true
terminologyServiceApi = "http://localhost:9090/fhir/r4"