/querying-terminology-service

name: querying-terminology-service
description: "Call a user-supplied FHIR terminology server ($validate-code, $expand, $lookup, $translate) to validate and expand clinical codes without bundling restricted vocabulary (SNOMED CT, RxNorm, LOINC, ICD-10) into OpenMed. Covers a thin local client, ValueSet $expand with filters/ECL, CodeSystem $lookup, ConceptMap $translate, and pointing at Ontoserver / HAPI / tx.fhir.org. Use as the grounding step for OpenMed coding skills — turn an OpenMed entity span into a validated coded CodeableConcept — when the user mentions terminology server, $validate-code, $expand, ValueSet, ECL, SNOMED/RxNorm/LOINC lookups, or code validation. Pairs adjacent."
license: Apache-2.0
metadata:
  project: OpenMed
  category: fhir-interop
  pairs: adjacent
  version: "1.0"

Querying a Terminology Service

OpenMed deliberately **bundles no restricted vocabulary** — no SNOMED CT, RxNorm, LOINC, ICD-10, UMLS. So when an OpenMed entity span needs a *validated* code (the grounding step `exporting-to-fhir` references), you call a **FHIR terminology server** the user already operates, with their own license. This skill is the thin client the coding skills lean on.

When to use

Use it whenever a span must become a *coded* `CodeableConcept`, when you need to confirm a code is valid in a system, expand a ValueSet for a picklist, look up a display, or map between vocabularies. Triggers: "terminology server", "$validate-code", "$expand", "ValueSet", "ECL", "is this a valid SNOMED/LOINC/ RxNorm code", "translate ICD-10 to SNOMED". It sits between OpenMed NER and `exporting-to-fhir`.

Bring your own server

The four operations are standard FHIR; point the client at whichever server the user is licensed for:

• **Ontoserver** (CSIRO) — production SNOMED CT/LOINC, full ECL.
• **HAPI FHIR** terminology module — self-hosted.
• **tx.fhir.org** — HL7 public server (open content only; **not** for licensed

SNOMED/full LOINC, and not for PHI).

OpenMed never ships or proxies these — the credentials and content are the user's.

The four operations

POST [tx]/CodeSystem/$validate-code   -> is this code valid in this system?
POST [tx]/ValueSet/$expand            -> enumerate the codes in a value set
POST [tx]/CodeSystem/$lookup          -> display + properties for a code
POST [tx]/ConceptMap/$translate       -> map a code from one system to another

`$validate-code` — confirm before you emit

curl -s -X POST 'https://tx.example/fhir/CodeSystem/$validate-code' \
  -H 'Content-Type: application/fhir+json' -d '{
    "resourceType": "Parameters",
    "parameter": [
      {"name": "url",  "valueUri":  "http://snomed.info/sct"},
      {"name": "code", "valueCode": "44054006"},
      {"name": "display", "valueString": "Diabetes mellitus type 2"}
    ]}'
# -> Parameters: { result: true, display: "Diabetes mellitus type 2" }

`$expand` — enumerate a ValueSet (with ECL for SNOMED)

# Expand "disorders of the lung" via an implicit SNOMED ECL value set
curl -s -X POST 'https://tx.example/fhir/ValueSet/$expand' \
  -H 'Content-Type: application/fhir+json' -d '{
    "resourceType": "Parameters",
    "parameter": [
      {"name": "url", "valueUri":
        "http://snomed.info/sct?fhir_vs=ecl/<<19829001"},
      {"name": "filter", "valueString": "pneumonia"},
      {"name": "count", "valueInteger": 20}
    ]}'

`<<19829001` is ECL for "19829001 (Disorder of lung) or any subtype". Use `$expand` + `filter` to power autocomplete and to constrain which codes a span may map to.

`$lookup` and `$translate`

# Display + properties for a LOINC code
POST [tx]/CodeSystem/$lookup  { url=http://loinc.org, code=4548-4 }

# Map an ICD-10-CM code to SNOMED via a ConceptMap
POST [tx]/ConceptMap/$translate {
  url=<conceptmap-url>, system=http://hl7.org/fhir/sid/icd-10-cm,
  code=E11.9, targetsystem=http://snomed.info/sct }

A thin client used by the coding skills

import requests

class TxClient:
    def __init__(self, base, token=None):
        self.base = base.rstrip("/")
        self.h = {"Content-Type": "application/fhir+json"}
        if token:
            self.h["Authorization"] = f"Bearer {token}"

    def _params(self, **kv):
        return {"resourceType": "Parameters",
                "parameter": [{"name": k, **v} for k, v in kv.items()]}

    def validate_code(self, system, code, display=None):
        body = self._params(url={"valueUri": system}, code={"valueCode": code},
                            **({"display": {"valueString": display}} if display else {}))
        out = requests.post(f"{self.base}/CodeSystem/$validate-code",
                            json=body, headers=self.h, timeout=15).json()
        params = {p["name"]: p for p in out.get("parameter", [])}
        return bool(params.get("result", {}).get("valueBoolean"))

# Ground an OpenMed span only if the code validates:
tx = TxClient("https://tx.example/fhir", token="...")
if tx.validate_code("http://snomed.info/sct", "44054006", "Diabetes mellitus type 2"):
    from openmed.clinical.exporters.codeable_concept_simple import coding, codeable_concept
    cc = codeable_concept([coding("snomed", "44054006",
                                  "Diabetes mellitus type 2")], text=span.text)

The system URIs here line up with OpenMed's `system_uri` (`snomed`/`loinc`/`rxnorm`/`icd-10-cm`/`hpo`/`mesh`), so a validated code drops straight into `coding(...)`.

Hand-off to / from OpenMed

• **From OpenMed:** an `EntityPrediction.text` (the span surface form) plus your

candidate code(s) are the input to `$validate-code`/`$translate`.

• **To OpenMed:** a *validated* (system, code, display) tuple →

`coding(...)` → `codeable_concept(...)` (`exporting-to-fhir`). If a span fails validation, emit `CodeableConcept` with only `text` and flag it via `OperationOutcomeIssue(severity="warning", code="code-invalid", ...)`.

• **No PHI to the server.** You send *codes and con