7. Terminology Validation

This section provides information about external terminology validation using remote terminology services.

7.1. Introduction

Since the last version of the openEHR SDK, EHRbase now offers the validation of external terminologies in addition to local and openehr ones.

This feature is based on constraints defined in the openEHR templates and allows to validate every single coded elements in a composition.

The following example demonstrates how to define the constraint in order to validate a coded element based on the standard value set http://hl7.org/fhir/ValueSet/surface define in HL7 FHIR.

<attributes xsi:type="C_SINGLE_ATTRIBUTE">
    <children xsi:type="C_CODE_REFERENCE">

According to the constraint defined above, a valid composition should look like (using a valid code coming from http://hl7.org/fhir/ValueSet/surface):

"value": {
    "_type": "DV_CODED_TEXT",
    "value": "Buccal",
    "defining_code": {
        "_type": "CODE_PHRASE",
        "terminology_id": {
            "_type": "TERMINOLOGY_ID",
            "value": "http://hl7.org/fhir/ValueSet/surface"
        "code_string": "B"

Otherwise the submitted composition will be rejected by EHRbase indicating the error.


The external terminology validation API available in the openEHR SDK module provides a generic mechanism that could be extended to support any remote terminology service.

However, please note that current implementation only supports FHIR terminology server.

7.2. Configuration

The following subsections provide information on the configuration of the external terminology validation in EHRbase.

7.2.1. Configuring EHRbase

EHRbase supports the following properties in order to properly configure the feature:

Key Default Value Description
validation.external-terminology.enabled false Whether to enable external terminology validation feature.
validation.external-terminology.fail-on-error false Indicates if validation should pass in case of connection error.
validation.external-terminology.provider.*   External terminology provider details.

The following application.yml illustrates how to configure the provider details:

# External Terminology Validation Properties
    enabled: true
    fail-on-error: true
       type: fhir
       url: https://r4.ontoserver.csiro.au/fhir
#     fhir-server-2:
#       type: fhir
#       url: https://localhost:9876/fhir
  • It is possible to register one or several providers.
  • As mention above, fhir is the only type currently supported.
  • The url property is the base URL of the terminology server.

7.2.2. Using provider with Two-Way SSL

If the remote terminology server requires to establish a communication channel using Two-Way SSL (Mutual Authentication), EHRBase can setup the SSL context used by HTTP client with the following configuration properties:

Key Default Value Description
client.ssl.enabled false Whether to enable SSL support.
client.ssl.key-password   Password used to access the key in the key store.
client.ssl.key-store   Path to the key store.
client.ssl.key-store-password   Password used to access the key store.
client.ssl.key-store-type   Type of the key store.
client.ssl.trust-store   Path to the trust store.
client.ssl.trust-store-password   Password used to access the trust store.
client.ssl.trust-store-type   Type of the trust store.

The following application.yml illustrates how to configure the SSL context:

# SSL Properties (used by Spring WebClient and Apache HTTP Client)
    enabled: true
    key-password: MySecretPassword
    key-store: C:/ehrbase/config/keystore.p12
    key-store-password: Azerty123456
    key-store-type: pkcs12
    trust-store: C:/ehrbase/config/truststore.p12
    trust-store-password: Qwerty123456
    trust-store-type: pkcs12