🔥 Hades : A HL7 FHIR terminology server 🔥

A lightweight HL7 FHIR server.

This is currently in development, but it currently works as a lightweight wrapper over hermes, a SNOMED CT terminology server.

The development plan is to turn this into a general purpose FHIR terminology server. Unlike most servers, it will be lightweight and principally designed to operate read-only. It will provide access to terminology services via a pluggable architecture, permitting the use of backend servers (such as hermes for SNOMED CT) together with an ability to import general purpose and custom value sets from the filesystem.

Background

The HL7 FHIR specification includes support for a terminology API, including looking up codes and translation.

This software currently provides a simple FHIR server implementation, making use of the HAPI FHIR library in order to expose the functionality available in hermes via a FHIR terminology API.

However, the FHIR terminology specification is quite simple, defining a HTTP REST API through which terminology data can be returned. In static languages, such as Java, one must take the FHIR specifications and generate code from those specifications. That code is then used to generate data. In dynamic languages, while code generation can be used, it makes more sense to just process data.

The current development plan is therefore to develop hades as a generic FHIR terminology server, which can provide access to multiple codesystems including those in the FHIR standard, as well as external codesystems such as SNOMED CT. For small codesystems, and the codesystems that form part of FHIR itself, these can be imported directly from the local filesystem in their canonical formats. For larger codesystems, such as SNOMED CT, an external library such as hermes, can be used.

Historically, I have not usually advised using a FHIR terminology server in order to fully make use of SNOMED CT in health and care applications. In essence, the FHIR terminology standard supposes that you might wish to treat terminologies interchangeably, but any real usage outside of trivial applications ends up making use of ad-hoc extensions that are usually terminology server specific. As such, you end up simply using the FHIR standard as a transport.

However, there is a need to be able to handle certain aspects of codesystems in a generic way, and the FHIR terminology specification enables that approach. We need good tooling to make sense of codes in context, independent of source applications.

The core principles behind the design of hades are therefore:

• dynamic pluggable codesystems
• immutability by default - prefer to build a new service rather than changing-in-place - load codesystems declaratively and reproducibly with versioning
• codesystems can be loaded from FHIR resources (e.g local JSON for built-in FHIR codesystems), custom modules (e.g. for SNOMED CT via hermes), or local data such as CSV, JSON and EDN.

The [FHIR terminology service standard] defines the following endpoints:

• Specific results in the capabilities endpoint to list supported codesystems
• [base]/ValueSet
  • Value set expansion : e.g. GET [base]/ValueSet/23/$expand?filter=abdo
  • Value set validation : e.g. GET [base]/ValueSet/23/$validate-code?system=http://loinc.org&code=1963-8&display=test
  • Batch validation
• [base]/CodeSystem
  • Concept lookup : e.g. GET [base]/CodeSystem/loinc/$lookup?code=1963-8 or GET [base]/CodeSystem/$lookup?system=http://loinc.org&code=1963-8&property=code&property=display&property=designations
  • Subsumption testing : e.g. GET [base]/CodeSystem/$subsumes?system=http://snomed.info/sct&codeA=235856003&codeB=3738000
• [base]/ConceptMap
  • Translation : e.g. GET [base]/ConceptMap/$translate?system=http://hl7.org/fhir/composition-status &code=preliminary&source=http://hl7.org/fhir/ValueSet/composition-status &target=http://terminology.hl7.org/ValueSet/v3-ActStatus
  • Batch translation - see [[https://hl7.org/fhir/terminology-service.html#batch2]](https://hl7.org/fhir/terminology-service.html#batch2

This means that the architecture contains the following modules:

• server - a web server with routes for a FHIR terminology server /ValueSet /CodeSystem and /ConceptMap
• format - processing to parse and emit appropriately structured JSON and XML to and from FHIR standard
• registry - a registry of supported codesystems and how they are implemented
• implementations - different codesystems will have different implementations of each capability
• import - a mechanism to import codesystems / valuesets from a filesystem, or another FHIR server, and make them available, or cached, within hades.

Current development roadmap

hades can already be used in production as a lightweight FHIR terminology server for SNOMED CT, but it does not yet support other codesystems. Such support will be straightforward, and we simply need to add additional 'pluggable' modules into the registry.

The roadmap for development is

• proof-of-concept FHIR terminology server
• pluggable architecture with dynamic registration of codesystems, value sets and concept maps
• add ability to use hermes as a codesystem, value and concept map 'provider'
• exploratory work to determine whether better to forego using the HAPI FHIR library in favour of directly returning data. Initial experiments suggest this is possible, but not for XML support.
• add ability to load in and register FHIR value sets from the specification
• add ability to load in and register custom value sets from the local filesystem, using JSON, EDN or CSVW
• add Java and Clojure APIs for FHIR terminology capabilities when used as a library
• improvements to CLI options
• build declarative configuration to permit users to choose which codesystems are made available through the hades terminology service
• consider exposing functions from hermes to automate the download and installation of SNOMED CT distributions via the hades CLI - make it easier for users to not worry about matching versions for compatibility.
• add support to test subsumption across codesystems when a map can be found to a common codesystem that permits subsumption testing (e.g. one could test a Read code against ICD-10 by mapping both to SNOMED CT first)

Quickstart

You can run a FHIR SNOMED CT terminology server directly from source code, if you have the clojure command line tools installed:

clj -M:run /path/to/snomed.db 8080

Otherwise, you can download a pre-built jar file.

java -jar hades-server-v0.10.xxx.jar /path/to/snomed/db 8080

Result:

➜  hades git:(main) ✗ clj -M:run /var/hermes/snomed-2021-03.db 8080
2021-03-23 14:50:57,175 [main] INFO  com.eldrix.hermes.terminology - hermes terminology service opened  "/var/hermes/snomed-2021-03.db" {:version 0.4, :store "store.db", :search "search.db", :created "2021-03-08T16:16:50.973088", :releases ("SNOMED Clinical Terms version: 20200731 [R] (July 2020 Release)" "31.3.0_20210120000001 UK clinical extension")}
2021-03-23 14:50:57,284 [main] INFO  org.eclipse.jetty.server.Server - jetty-9.4.18.v20190429; built: 2019-04-29T20:42:08.989Z; git: e1bc35120a6617ee3df052294e433f3a25ce7097; jvm 11.0.9.1+1
2021-03-23 14:50:57,346 [main] INFO  com.eldrix.hades.core - Initialising HL7 FHIR R4 server; providers: CodeSystem
2021-03-23 14:50:58,308 [main] INFO  org.eclipse.jetty.server.Server - Started @14980ms

How do I create a SNOMED database file?

Use hermes to create your index file. That tool can automatically download and create an index. After download, it should take less than 5 minutes to start running your FHIR terminology server.

You need to use the correct version of hermes. For hades v1.4 series, use hermes v1.4 series.

Example usage

Here are some examples of using the FHIR terminology API:

Lookup a SNOMED code

curl -H "Accept: application/json" 'localhost:8080/fhir/CodeSystem/$lookup?system=http://snomed.info/sct&code=209629006'

How do two codes relate to one another?

Here we test how 107963000|Liver excision relates to 63816008|Hepatectomy, total left lobectomy (procedure).

curl -H "Accept: application/json" 'localhost:8080/fhir/CodeSystem/$subsumes?system=http://snomed.info/sct&codeA=107963000&codeB=63816008&_format=json' | jq

Result:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "outcome",
      "valueString": "subsumes"
    }
  ]
}

Expand a valueset

Here we ask for the contents of a valueset as defined by the URL http://snomed.info/sct?fhir_vs=ecl/<<50043002%20:<<263502005=<<19939008, that is, give me any concepts that match the constraint

• Disorder of the respiratory system (<<50043002)
• with a clinical course (<<263502005) (or any more specific subtype of 'clinical course')
• of subacute (<<19939008)

Of course, you can use any ECL expression and add an optional filter as well. If you add &filter=sili then you'll basically have an endpoint that can drive fast autocompletion.

curl -H "Accept: application/json" 'localhost:8080/fhir/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=ecl/<<50043002:<<263502005=<<19939008' | jq

Result

{
  "resourceType": "ValueSet",
  "expansion": {
    "total": 13,
    "contains": [
      {
        "system": "http://snomed.info/sct",
        "code": "233761006",
        "display": "Subacute silicosis",
        "designation": [
          {
            "value": "Active silicosis"
          }
        ]
      },
      {
        "system": "http://snomed.info/sct",
        "code": "233761006",
        "display": "Subacute silicosis",
        "designation": [
          {
            "value": "Subacute silicosis"
          }
        ]
      },
      {
        "system": "http://snomed.info/sct",
        "code": "233753001",
        "display": "Subacute berylliosis",
        "designation": [
          {
            "value": "Subacute berylliosis"
          }
        ]
      },
      {
        "system": "http://snomed.info/sct",
        "code": "22482002",
        "display": "Subacute obliterative bronchiolitis",
        "designation": [
          {
            "value": "Subacute obliterative bronchiolitis"
          }
        ]
      },
      {
        "system": "http://snomed.info/sct",
        "code": "782761005",
        "display": "Subacute invasive pulmonary aspergillosis",
        "designation": [
          {
            "value": "Subacute invasive pulmonary aspergillosis"
          }
        ]
      },
      {
        "system": "http://snomed.info/sct",
        "code": "782761005",
        "display": "Subacute invasive pulmonary aspergillosis",
        "designation": [
          {
            "value": "Chronic necrotising pulmonary aspergillosis"
          }
        ]
      },
      {
        "system": "http://snomed.info/sct",
        "code": "782761005",
        "display": "Subacute invasive pulmonary aspergillosis",
        "designation": [
          {
            "value": "Chronic necrotizing pulmonary aspergillosis"
          }
        ]
      },
      {
        "system": "http://snomed.info/sct",
        "code": "836479005",
        "display": "Subacute obliterative bronchiolitis due to vapour",
        "designation": [
          {
            "value": "Subacute obliterative bronchiolitis due to vapor"
          }
        ]
      },
      {
        "system": "http://snomed.info/sct",
        "code": "836479005",
        "display": "Subacute obliterative bronchiolitis due to vapour",
        "designation": [
          {
            "value": "Subacute obliterative bronchiolitis due to vapour"
          }
        ]
      },
      {
        "system": "http://snomed.info/sct",
        "code": "836479005",
        "display": "Subacute obliterative bronchiolitis due to vapour",
        "designation": [
          {
            "value": "Subacute obliterative bronchiolitis caused by vapor"
          }
        ]
      },
      {
        "system": "http://snomed.info/sct",
        "code": "836479005",
        "display": "Subacute obliterative bronchiolitis due to vapour",
        "designation": [
          {
            "value": "Subacute obliterative bronchiolitis caused by vapour"
          }
        ]
      },
      {
        "system": "http://snomed.info/sct",
        "code": "836478002",
        "display": "Subacute obliterative bronchiolitis due to chemical fumes",
        "designation": [
          {
            "value": "Subacute obliterative bronchiolitis due to chemical fumes"
          }
        ]
      },
      {
        "system": "http://snomed.info/sct",
        "code": "836478002",
        "display": "Subacute obliterative bronchiolitis due to chemical fumes",
        "designation": [
          {
            "value": "Subacute obliterative bronchiolitis caused by chemical fumes"
          }
        ]
      }
    ]
  }
}

Original (and now outdated) design / development notes

see https://confluence.ihtsdotools.org/display/FHIR/Implementing+Terminology+Services+with+SNOMED+CT

The operations that are currently implemented (although are still under continued refinement and development) are:

• $lookup (on CodeSystem resource)
• $subsumes (on CodeSystem resource)
• $expand (on ValueSet resource) - e.g. ECL, filters

The operations that still need to be implemented are:

• $closure (on ConceptMap resource)
• $translate (on ConceptMap resource)
• $validate-code (on ValueSet resource)
• $validate-code (on CodeSystem resource)

Resource implementations are needed for

• CodeSystem - e.g. list all code systems available (higher-order services might compose the results for example)

All of this functionality is obviously available in hermes but we need to expose using these FHIR operations.

I don't believe in loading random value sets into a single terminology server. Rather, these should be decomposed and recombined as needed. Otherwise, developers solving problems need to coordinate with a central authority in order to ensure the value sets and reference data they need are available. The exact choice will be determined by the problem-at-hand. Decompose, make them available both as raw data and discrete computing services that makes using them easy, and then let others compose them together to suit their needs.