Building a LOINC-to-Local Code Crosswalk in Python

Problem Statement

Analyzers speak local codes — K, NA+, CREA — and the rest of the pipeline speaks LOINC. The crosswalk between them is the single most safety-critical lookup table in a LIMS, because a wrong row does not error; it silently reports the wrong analyte under a plausible name. If the instrument’s CREA is mapped to LOINC 2823-3 (Potassium) instead of 2160-0 (Creatinine), every creatinine result flows into potassium reference ranges and delta checks, and nothing downstream can detect it. This page builds that crosswalk as a validated, versioned artifact in Python with Pydantic v2: typed rows that reject a malformed LOINC at load time, deterministic resolution keyed on (instrument_model, local_code, specimen), explicit handling for unmapped codes that holds rather than guesses, and a version stamp that lets an inspector reconstruct which mapping was live when a result was reported.

Prerequisites

Before this crosswalk becomes the authority for analyte identity, confirm:

• Runtime: Python 3.11+, pydantic>=2.6 for the row and table models, pytest>=8 for the resolution fixtures.
• Source of local codes: the instrument-side vocabulary comes from the HL7 v2 segment mapping stage, where OBX-3 carries a local code and coding system that this crosswalk resolves to LOINC before the identity is trusted.
• LOINC reference: access to the official LOINC table (loinc.org) to validate that a target code exists and to seed display names; the crosswalk stores the code, not a private redefinition of it.
• Governance: a change-control process, because every edit to a mapping row is a change to what the laboratory reports and must be versioned and reviewable.

Step-by-Step Implementation

Step 1: Model the crosswalk row with validation at ingress

Model each mapping as a Pydantic v2 CrosswalkRow so a malformed LOINC — wrong shape, missing check digit — fails at load rather than at the bedside. LOINC codes are NNNN-N through NNNNNNN-N with a Mod-10 check digit; validate the shape with a pattern and keep the specimen and instrument in the key so the same local code can map differently across analyzers.

from __future__ import annotations

import re
from pydantic import BaseModel, Field, field_validator

LOINC_RE = re.compile(r"^\d{1,7}-\d$")


class CrosswalkRow(BaseModel):
    instrument_model: str
    local_code: str
    specimen: str                 # e.g. "serum", "plasma", "whole-blood"
    loinc: str
    loinc_display: str
    unit_ucum: str
    active: bool = True

    @field_validator("loinc")
    @classmethod
    def _valid_loinc_shape(cls, v: str) -> str:
        if not LOINC_RE.match(v):
            raise ValueError(f"{v!r} is not a well-formed LOINC code (NNNN-N)")
        return v

    @field_validator("local_code")
    @classmethod
    def _normalize_local(cls, v: str) -> str:
        return v.strip().upper()  # analyzers vary on case and whitespace

Step 2: Load the table into a deterministic index

Load rows from a versioned source (a checked-in YAML or a governed database export) into an index keyed on (instrument_model, local_code, specimen). Reject duplicate keys at load time — two active rows for the same key is an ambiguity that must never resolve nondeterministically. Stamp the table with a version so the audit can name it.

from pydantic import BaseModel


class CrosswalkTable(BaseModel):
    version: str
    rows: list[CrosswalkRow]

    def build_index(self) -> dict[tuple[str, str, str], CrosswalkRow]:
        index: dict[tuple[str, str, str], CrosswalkRow] = {}
        for row in self.rows:
            if not row.active:
                continue
            key = (row.instrument_model, row.local_code, row.specimen)
            if key in index:
                raise ValueError(f"duplicate active crosswalk key {key!r}")
            index[key] = row
        return index

Step 3: Resolve a local code, holding on miss

Resolution is a pure function over the index. A hit returns the mapped LOINC identity; a miss returns an explicit Unmapped marker rather than a guess, so the caller routes the result to a manual-mapping hold. Guessing — nearest string, most-common LOINC — is the one thing a crosswalk must never do.

from dataclasses import dataclass


@dataclass(frozen=True)
class Resolved:
    loinc: str
    loinc_display: str
    unit_ucum: str
    table_version: str


@dataclass(frozen=True)
class Unmapped:
    instrument_model: str
    local_code: str
    specimen: str
    table_version: str


class CrosswalkResolver:
    def __init__(self, table: CrosswalkTable) -> None:
        self._version = table.version
        self._index = table.build_index()

    def resolve(
        self, *, instrument_model: str, local_code: str, specimen: str
    ) -> Resolved | Unmapped:
        key = (instrument_model, local_code.strip().upper(), specimen)
        row = self._index.get(key)
        if row is None:
            return Unmapped(instrument_model, key[1], specimen, self._version)
        return Resolved(row.loinc, row.loinc_display, row.unit_ucum, self._version)

Step 4: Version the crosswalk and audit each resolution

Every resolution — hit or miss — must record which table version answered it, so a result reported under version 2026.07.1 remains reconstructable after the table changes. The audit is a plain Pydantic model round-tripped to the append-only sink.

import datetime as dt
from pydantic import BaseModel, Field


class ResolutionAudit(BaseModel):
    trace_id: str
    instrument_model: str
    local_code: str
    specimen: str
    resolved_loinc: str | None
    table_version: str
    mapped: bool
    resolved_at: dt.datetime = Field(
        default_factory=lambda: dt.datetime.now(dt.timezone.utc)
    )


def audit_resolution(trace_id: str, outcome: Resolved | Unmapped) -> ResolutionAudit:
    mapped = isinstance(outcome, Resolved)
    return ResolutionAudit(
        trace_id=trace_id,
        instrument_model=getattr(outcome, "instrument_model", "")
        if isinstance(outcome, Unmapped) else "",
        local_code=outcome.local_code if isinstance(outcome, Unmapped) else "",
        specimen=outcome.specimen if isinstance(outcome, Unmapped) else "",
        resolved_loinc=outcome.loinc if mapped else None,
        table_version=outcome.table_version,
        mapped=mapped,
    )

Sample Crosswalk

A realistic slice of a chemistry analyzer’s crosswalk. Local codes are analyzer-specific; the LOINC column is the universal identity every downstream stage keys on.

Verification & Testing

Prove the two failure modes that matter: a duplicate active key must be refused at load, and a miss must return Unmapped rather than a nearest guess. Round-trip the audit so the record is byte-stable.

import pytest

TABLE = CrosswalkTable(
    version="2026.07.1",
    rows=[
        CrosswalkRow(instrument_model="Analyzer-X", local_code="k", specimen="serum",
                     loinc="2823-3", loinc_display="Potassium", unit_ucum="mmol/L"),
        CrosswalkRow(instrument_model="Analyzer-X", local_code="CREA", specimen="serum",
                     loinc="2160-0", loinc_display="Creatinine", unit_ucum="mg/dL"),
    ],
)


def test_resolves_case_insensitively():
    r = CrosswalkResolver(TABLE)
    out = r.resolve(instrument_model="Analyzer-X", local_code="K", specimen="serum")
    assert isinstance(out, Resolved)
    assert out.loinc == "2823-3"
    assert out.table_version == "2026.07.1"


def test_unknown_code_holds_not_guesses():
    r = CrosswalkResolver(TABLE)
    out = r.resolve(instrument_model="Analyzer-X", local_code="GLU", specimen="serum")
    assert isinstance(out, Unmapped)
    assert audit_resolution("t1", out).mapped is False


def test_duplicate_active_key_rejected():
    dupe = CrosswalkTable(version="x", rows=[TABLE.rows[0], TABLE.rows[0]])
    with pytest.raises(ValueError, match="duplicate"):
        CrosswalkResolver(dupe)

Expected: all three tests pass. test_resolves_case_insensitively confirms the local_code normalizer; test_unknown_code_holds_not_guesses confirms a miss holds rather than fabricating an identity; test_duplicate_active_key_rejected confirms load-time ambiguity detection. A malformed LOINC such as "2823" should raise from the row validator before it ever reaches the index.

Compliance Note

CAP checklist item GEN.40350 and the CLIA §493.1291 reporting requirement both hinge on the laboratory reporting the correct test under a correct, documented identity; a crosswalk that guesses violates that at the root. Stamping each resolution with table_version and writing a ResolutionAudit to an append-only sink satisfies the 21 CFR Part 11 expectation that the mapping in force at report time be attributable and reconstructable, and holding unmapped codes rather than guessing keeps an unrecognized analyte off the patient report until a qualified reviewer maps it. Because the crosswalk stores the LOINC code and not a private redefinition, it stays reconcilable with the official LOINC release the laboratory validated against.

Troubleshooting

Related

• Test Code Taxonomy & Standards — the governance context this crosswalk operates inside.
• How to Map LOINC Codes to LIMS Test Panels — groups the LOINC identities this crosswalk resolves into orderable panels.
• Building a LOINC / SNOMED CT Code-Mapping Reference — extends the crosswalk pattern to the SNOMED CT bindings reporting needs.
• Terminology & Code Mapping References — the reference subsystem that consumes these resolved LOINC identities downstream.
• Mapping HL7 v2 OBX Segments to LIMS Result Fields — where a non-LOINC OBX-3 coding system is handed to this crosswalk.

Part of: Test Code Taxonomy & Standards.