Reasonhub Terminology Crossmap

Terminology Crossmap → SNOMED

Overview

ICD-10-CM, LOINC, and RxNorm all have strong use cases but limited semantic depth. SNOMED CT's attribute model (finding site, causative agent, associated morphology, etc.) is unmatched for answering clinical relationship questions.

This skill bridges the gap: given a code in any system, find its SNOMED equivalent and then use the snomed-semantic skill to query relationships.

No formal crossmap table is loaded. Mapping uses semantic search (search_snomed) on the source concept's display name. Always verify the match before proceeding.

When to Propose a Crossmap

Proactively suggest crossmapping to SNOMED when:

• The user has an ICD-10-CM code and asks "what is related to this?"
• The user has a LOINC observation code and wants to understand the clinical domain semantically
• The user has an RxNorm ingredient and wants to find all disorders it treats or all procedures that use it
• The user asks about "symptoms of X", "conditions caused by X", or "procedures for X" using a non-SNOMED code

Workflow

Phase 1 — Look up the source code

codesystem_lookup(code="<source_code>", system="<source_system>")

Extract the display. This is the search query for Phase 2.

codesystem_lookup("I25.10", "http://hl7.org/fhir/sid/icd-10-cm")
# display: "Atherosclerotic heart disease of native coronary artery
#            without angina pectoris"

Phase 2 — Search SNOMED for the equivalent

Run this in parallel with Phase 1 if the source display is already known.

search_snomed(query="coronary arteriosclerosis disorder", top_k=5)

Selection heuristics:

• ICD-10 diagnosis → prefer (disorder) semantic tag
• LOINC observation → prefer (observable entity)
• RxNorm ingredient → prefer (substance)
• Prefer sufficientlyDefined = true (richer attributes)
• When ambiguous, present 2–3 candidates and ask the user

Phase 3 — Confirm the match and extract the pivot

codesystem_lookup(code="53741008", system="http://snomed.info/sct")

Check inactive = false and display matches. Then read the finding site attribute (363698007) directly from the response — this is the body structure concept ID you will use as the procedure site filter value in Phase 4.

# Coronary arteriosclerosis (53741008)
# 363698007 (Finding site) = 41801008 (Coronary artery structure)  ← pivot

This pivot step is the bridge between the diagnosis code and the procedure ValueSet. The disorder’s finding site becomes the procedure’s site filter value.

Phase 4 — Discover the procedure site attribute

Before building the filter, look up one known representative procedure from the target domain to confirm which attribute it uses. Run this in parallel with Phase 3 if you already have a candidate procedure in mind.

codesystem_lookup("415070008", "http://snomed.info/sct")  # PCI
# 363704007 (Procedure site - Direct)   = 41801008  ← present
# 405813007 (Procedure site - Indirect) = 41801008  ← also present

codesystem_lookup("232717009", "http://snomed.info/sct")  # CABG
# 363704007 (Procedure site - Direct)   = — not present
# 405813007 (Procedure site - Indirect) = 41801008  ← only Indirect

Rule: use 405813007 (Indirect) when it appears on all representative concepts. 363704007 (Direct) alone will miss procedures coded only to Indirect. When unsure, look up two or three known procedures and check.

Phase 5 — Build the ValueSet filter

Use the confirmed site attribute + pivot concept ID + procedure hierarchy:

{
  "resourceType": "ValueSet",
  "name": "CoronaryArteryProcedures",
  "title": "Procedures on the Coronary Artery",
  "status": "draft",
  "compose": {
    "include": [{
      "system": "http://snomed.info/sct",
      "version": "<from list_available_codesystem_versions>",
      "filter": [
        { "property": "405813007", "op": "=",   "value": "41801008" },
        { "property": "concept",   "op": "is-a", "value": "71388002" },
        { "property": "inactive",  "op": "=",   "value": "false" }
      ]
    }]
  }
}

71388002 is the SNOMED root for Procedure. Always include it to avoid non-procedure concepts that may also encode a procedure site attribute.

Source System Guidance

ICD-10-CM → SNOMED

ICD-10-CM codes map well to SNOMED disorders and findings.

Tip: ICD-10 codes are intentionally coarser than SNOMED. A single ICD-10 code can map to multiple SNOMED concepts. Choose the most clinically appropriate one for the query goal.

Example crossmap:

ICD-10:  E11.9  "Type 2 diabetes mellitus without complications"
SNOMED:  44054006  "Type 2 diabetes mellitus"  (disorder)

Once mapped, SNOMED lets you find:

• All disorders with causative agent = insulin resistance mechanism
• All subtypes via concept is-a 44054006
• All finding sites affected: 363698007 = <pancreas / various>

RxNorm → SNOMED

RxNorm ingredients map to SNOMED substances or products.

Example crossmap:

RxNorm:  1049502  "metformin 500 MG Oral Tablet"
→ Strip to ingredient: metformin
SNOMED:  372567009  "Metformin"  (substance)

Once mapped, SNOMED lets you find:

• Disorders where this substance is the causative agent (246075003)
• Procedures that use this substance
• Other substances in the same chemical class via hierarchy

RxNorm ingredient extraction tip: If the RxNorm code is a SCD/SBD (drug + dose form + strength), first extract just the ingredient name using codesystem_lookup then search SNOMED on the ingredient name alone.

LOINC → SNOMED

LOINC observation codes map to SNOMED observable entities or procedures.

⚠️ SNOMED chemistry analyte caveat: Most common chemistry lab analytes (glucose, creatinine, ALT, sodium, calcium, etc.) do not have active (observable entity) concepts in SNOMED CT. The best active pivots are almost always (finding) with a “level – finding” display, or (procedure) with a “measurement” display. Accept the best active match from the first search_snomed call regardless of semantic tag. Do not run additional search rounds specifically hunting for (observable entity) — it rarely exists for common chemistry analytes and the search will not find what isn’t there.

Example crossmap:

LOINC:   2339-0  "Glucose [Mass/volume] in Blood"
SNOMED:  33747003  "Blood glucose measurement"  (procedure)
         or
         434912009  "Blood glucose concentration"  (observable entity)

Getting the COMPONENT LP code for a LOINC observation

The COMPONENT LP code (e.g., LP14635-4 for Glucose) is returned directly by codesystem_lookup on any LOINC observation code. Read it from the response — do not guess it, do not search loinc.org:

codesystem_lookup("2345-7", "http://loinc.org")
# COMPONENT = LP14635-4 (Glucose)   ← use this in COMPONENT filter
# SYSTEM    = LP7576-4  (Ser/Plas)  ← use this in SYSTEM filter

Getting the members of a LOINC panel

codesystem_lookup on a panel code returns the panel’s own axes but NOT its members. To get members, expand with a panel-parent filter:

{
  "resourceType": "ValueSet",
  "compose": {
    "include": [{
      "system": "http://loinc.org",
      "version": "<version>",
      "filter": [
        { "property": "panel-parent", "op": "=", "value": "24323-8" }
      ]
    }]
  }
}

Expand this with reasonhub-skills expand to get the full member list.

The result includes the panel code itself and any nested panel codes — filter to unique codes before processing. Then call codesystem_lookup on each member to get its COMPONENT and SYSTEM LP codes. Do this via the API — do not fetch individual loinc.org/CODE pages to extract LP codes.

codesystem_lookup("2345-7", "http://loinc.org")
# COMPONENT = LP14635-4  ← use this in COMPONENT filter
# SYSTEM    = LP7576-4   ← note for context only — do NOT expand it (see below)

To find sibling observations sharing the same COMPONENT, use reasonhub-skills expand with a COMPONENT = <LP_CODE> filter — not search_loinc. search_loinc returns semantically similar observations, not structurally related ones sharing the same LOINC axis.

Do not expand SYSTEM. For CMP-class analytes, SYSTEM = LP7576-4 (Ser/Plas) matches 1001 active LOINC codes spanning blood typing antibodies, food IgGs, viral loads, and oncology panels — none of them related to the analyte in question. Just report the LP code and count. COMPONENT is the discriminating axis for this query pattern.

{
  "resourceType": "ValueSet",
  "compose": {"include": [{
    "system": "http://loinc.org",
    "version": "<version>",
    "filter": [
      { "property": "COMPONENT", "op": "=", "value": "<LP_CODE_FROM_LOOKUP>" },
      { "property": "STATUS",    "op": "=", "value": "ACTIVE" }
    ]
  }]}
}

⛔ Do not scrape loinc.org pages to get panel structure or LP codes. Do not use search_loinc to find LP codes for analytes — search_loinc returns semantic proximity matches, not the exact LP code bound to a given LOINC observation. The LP code is in the codesystem_lookup response. Do not use search_loinc for sibling finding by COMPONENT or SYSTEM axis. All three are available through structured API calls.

Handling Ambiguous Mappings

When search_snomed returns multiple plausible matches:

1. Narrow with a more specific query: add the semantic domain ("myocardial infarction disorder", "glucose substance")
2. Compare parent properties — the right SNOMED concept sits under the expected parent hierarchy
3. Use codesystem_subsumes to verify the candidate is in the right subtree:

   codesystem_subsumes(
     code_a="64572001",   # Disease
     code_b="<candidate>",
     system="http://snomed.info/sct"
   )
   

4. If still ambiguous, present candidates with their display, semanticTag, and parent names. Let the user choose.

Full Example: I25.10 → SNOMED → Coronary Procedure ValueSet

User request: "We have I25.10 in our encounter data and need a ValueSet of coronary procedures — PCI, CABG, angiography, stent placement."

Phase 1 — Look up ICD-10 display:

codesystem_lookup("I25.10", "http://hl7.org/fhir/sid/icd-10-cm")
# display: "Atherosclerotic heart disease of native coronary artery
#            without angina pectoris"

Phase 2 — Search SNOMED (run in parallel with Phase 1 if display is known):

search_snomed("coronary arteriosclerosis disorder", top_k=5)
# Top match: 53741008 "Coronary arteriosclerosis" (disorder)

Phase 3 — Confirm and extract pivot (run in parallel with a known procedure lookup):

codesystem_lookup("53741008", "http://snomed.info/sct")
# sufficientlyDefined = true
# 363698007 (Finding site) = 41801008 (Coronary artery structure)  ← pivot

Phase 4 — Discover procedure site attribute:

# Run in parallel with Phase 3
codesystem_lookup("415070008", "http://snomed.info/sct")  # PCI
# 363704007 (Direct)   = 41801008  ← present
# 405813007 (Indirect) = 41801008  ← present

codesystem_lookup("232717009", "http://snomed.info/sct")  # CABG
# 363704007 (Direct)   = — not present
# 405813007 (Indirect) = 41801008  ← only Indirect

# → use 405813007 — it covers both PCI and CABG

Phase 5 — ConceptMap + ValueSet output:

ConceptMap (source → SNOMED pivot):

{
  "resourceType": "ConceptMap",
  "name": "I2510ToSNOMED",
  "title": "Atherosclerotic heart disease of native coronary artery without angina pectoris → SNOMED CT",
  "status": "draft",
  "sourceUri": "http://hl7.org/fhir/sid/icd-10-cm",
  "targetUri": "http://snomed.info/sct",
  "group": [{
    "source": "http://hl7.org/fhir/sid/icd-10-cm",
    "target": "http://snomed.info/sct",
    "targetVersion": "http://snomed.info/sct/731000124108/version/20250901",
    "element": [{
      "code": "I25.10",
      "display": "Atherosclerotic heart disease of native coronary artery without angina pectoris",
      "target": [{
        "code": "53741008",
        "display": "Coronary arteriosclerosis",
        "equivalence": "wider",
        "comment": "ICD-10-CM I25.10 specifies absence of angina; SNOMED 53741008 is broader. Verify clinical fit before use."
      }]
    }]
  }]
}

ValueSet (procedures at pivot site):

{
  "resourceType": "ValueSet",
  "name": "CoronaryArteryProcedures",
  "title": "Procedures on the Coronary Artery (SNOMED CT)",
  "status": "draft",
  "compose": {
    "include": [{
      "system": "http://snomed.info/sct",
      "version": "http://snomed.info/sct/731000124108/version/20250901",
      "filter": [
        { "property": "405813007", "op": "=",   "value": "41801008" },
        { "property": "concept",   "op": "is-a", "value": "71388002" },
        { "property": "inactive",  "op": "=",   "value": "false" }
      ]
    }]
  }
}

After Crossmapping

Once you have the SNOMED concept ID, follow the snomed-semantic skill for the full set of relationship query patterns.

Output

Every crossmap delivers three things.

1. Crossmap provenance (always)

Show the mapping chain so the user can verify it:

2. FHIR ConceptMap JSON (always)

Emit a complete ConceptMap resource capturing the source → SNOMED mapping. This is the machine-readable artifact users can load into a FHIR server or validation tool to verify the crossmap.

Equivalence guidance (R4 equivalence codes):

ICD-10 codes are almost always wider or inexact; note the reason in comment.

Template:

{
  "resourceType": "ConceptMap",
  "name": "<SourceCode>ToSNOMED",
  "title": "<Source display> → SNOMED CT",
  "status": "draft",
  "sourceUri": "<source_system>",
  "targetUri": "http://snomed.info/sct",
  "group": [{
    "source": "<source_system>",
    "sourceVersion": "<source_version>",
    "target": "http://snomed.info/sct",
    "targetVersion": "<snomed_version>",
    "element": [{
      "code": "<source_code>",
      "display": "<source_display>",
      "target": [{
        "code": "<snomed_code>",
        "display": "<snomed_display>",
        "equivalence": "<equivalence_code>",
        "comment": "<reason — e.g. ICD-10 is coarser; verify clinical fit>"
      }]
    }]
  }]
}

Worked example (I25.10 → SNOMED):

{
  "resourceType": "ConceptMap",
  "name": "I2510ToSNOMED",
  "title": "Atherosclerotic heart disease of native coronary artery without angina pectoris → SNOMED CT",
  "status": "draft",
  "sourceUri": "http://hl7.org/fhir/sid/icd-10-cm",
  "targetUri": "http://snomed.info/sct",
  "group": [{
    "source": "http://hl7.org/fhir/sid/icd-10-cm",
    "target": "http://snomed.info/sct",
    "targetVersion": "http://snomed.info/sct/731000124108/version/20250901",
    "element": [{
      "code": "I25.10",
      "display": "Atherosclerotic heart disease of native coronary artery without angina pectoris",
      "target": [{
        "code": "53741008",
        "display": "Coronary arteriosclerosis",
        "equivalence": "wider",
        "comment": "ICD-10-CM I25.10 specifies absence of angina; SNOMED 53741008 is broader. Verify clinical fit before use."
      }]
    }]
  }]
}

Always include both display values (source and target) so the ConceptMap is human-readable without a terminology server lookup.

3. FHIR ValueSet JSON + optional expansion

Deliver the complete ValueSet resource. Then ask:

"Would you like me to expand this to preview the matching procedure codes? I can show results as a markdown table or CSV."

Attempt valueset_expand once if the user says yes. If expansion returns fewer rows than total, label the output as partial and stop. Do not retry. See reasonhub-expand-mechanics for expand failures, CLI fallback, and debugging.

CSV format:

code,display
415070008,"Percutaneous coronary intervention"
232717009,"Coronary artery bypass graft"
33367005,"Angiography of coronary artery"