OMOP Vocabulary Mapping: Local Codes to Standard Concepts
OMOP vocabulary mapping is the process of linking every code in a source dataset, whether a standard terminology like ICD-10 or a hospital’s own local code, to a standard concept in the OHDSI vocabularies. Done well, it lets the same analysis run unchanged across any OMOP database; done poorly, it silently drops patients or puts records in the wrong clinical domain.
Why vocabulary mapping decides the value of an OMOP database
The OMOP Common Data Model gives every database the same tables. That alone does not make data comparable. Two hospitals can both load a CONDITION_OCCURRENCE table and still describe the same disease with different codes. Standard concepts are what make a query for “type 2 diabetes” return the same kind of patient everywhere.
This matters more as programs scale. National initiatives and research networks increasingly combine data from dozens of sources, often through federated analysis where one query runs at many sites. If one site’s mapping is incomplete, its results look different for reasons that have nothing to do with medicine. Vocabulary work is therefore the foundation of trustworthy multi-site research, and the part of an OMOP project that most deserves careful review. For the model itself, see our guide to the OMOP CDM.
How the OHDSI vocabularies are organized
Concepts
Every term in every supported vocabulary is a row in the CONCEPT table with a numeric concept ID, a name, a vocabulary, a domain and a flag that says whether it is a standard concept. Standard concepts are the ones analyses should use. Source concepts, such as ICD-10-CM codes, are kept so that the original meaning is never lost.
Relationships
The CONCEPT_RELATIONSHIP table links concepts to each other. The most important relationship for mapping is “Maps to”, which points from a source concept to its standard equivalent. For example, an ICD-10-CM diagnosis code typically maps to a SNOMED CT standard concept. Hierarchies are held in the CONCEPT_ANCESTOR table, which is what lets a query for a broad condition find all of its more specific descendants.
Domains
Each standard concept belongs to a domain such as Condition, Drug, Measurement, Procedure or Observation. The domain of the mapped standard concept decides which OMOP table a record lands in. This is why mapping must happen before records are routed to tables.
Where the vocabularies come from
The vocabularies are downloaded from the OHDSI Athena service. Some, such as CPT-4, require a separate license. Vocabulary releases change over time, so record which release each database was built on.
Standard codes versus local codes
Source data falls into two groups, and they need very different amounts of work.
| Dimension | Standard source codes | Local or free-text codes |
|---|---|---|
| Examples | ICD-10, LOINC, RxNorm, SNOMED CT, ATC | Hospital lab codes, pharmacy item numbers, free-text diagnoses |
| Mapping method | Automatic lookup through “Maps to” relationships | Assisted matching plus clinical review |
| Effort | Low once vocabularies are loaded | High; often the bulk of an ETL project |
| Where stored | Already in the OHDSI vocabularies | SOURCE_TO_CONCEPT_MAP table or custom concepts |
| Main risk | Outdated vocabulary release | Wrong or missing matches that bias results |
| Review need | Spot checks | Every mapping reviewed and recorded |
A step-by-step OMOP vocabulary mapping workflow
- Inventory source codes. Extract every distinct code and description from each source field, with how often it occurs. Frequency tells you where review effort pays off most.
- Resolve standard codes first. Join codes from known vocabularies to the CONCEPT table, then follow “Maps to” relationships to standard concepts. Flag any codes that do not resolve.
- Match local codes. Use the OHDSI Usagi tool, or an AI-assisted matcher, to suggest candidate standard concepts from the code descriptions. Translate non-English descriptions first if needed.
- Review clinically. A reviewer with clinical or coding background accepts, corrects or rejects each suggestion. Record who approved each mapping and when.
- Store mappings. Load approved local mappings into the SOURCE_TO_CONCEPT_MAP table, or create custom concepts with IDs above 2,000,000,000, the range OHDSI reserves for local use.
- Apply in the ETL. Populate both the standard concept ID and the source concept ID and source value in every clinical table.
- Measure coverage. Report the share of distinct codes and the share of records mapped to a standard concept, by domain.
Quality rules for accurate mappings
Map to the most specific correct concept
If a source code means “type 2 diabetes with kidney complications”, do not map it to plain “diabetes mellitus”. Over-general mappings make cohorts look larger and less specific than they are.
Allow one-to-many where meaning requires it
Some source codes combine two ideas, such as a diagnosis and a body site, or a condition and a family history flag. OMOP allows a source code to map to more than one standard concept. Use it rather than forcing a poor single match.
Keep units with measurements
Laboratory mapping covers the test, the unit and sometimes the value. A LOINC test concept without a correct unit concept leaves results that cannot be compared across sites.
Never discard the source
Always keep the source value and source concept ID. When a mapping is corrected later, the database can be rebuilt without going back to the original system.
Version everything
Mapping tables, vocabulary releases and ETL code should all be versioned together. Each data release should state which versions it used, so that any published result can be reproduced. Our guide to health data quality covers how to track these measures over time.
Common mapping mistakes and how to catch them
- Unmapped high-frequency codes. Sort unmapped codes by record count. A handful of common local codes often account for a large share of missing data.
- Domain mismatches. Check that records land in the table matching their standard concept’s domain, and investigate any that do not.
- Deprecated concepts. After a vocabulary update, some standard concepts become non-standard. Rerun mapping checks with every vocabulary refresh.
- Silent drops. Records mapped to concept ID 0, meaning no matching concept, should be counted and reported, not hidden.
- Inconsistent reviewers. Write short mapping conventions so that different reviewers make the same choices for similar codes.
The OHDSI Data Quality Dashboard includes checks that catch several of these issues automatically, and Achilles characterization helps reviewers spot implausible distributions after mapping.
Mapping across many sites in a federated network
Vocabulary mapping is part of the wider discipline of data harmonization. In a multi-site network, the goal is not only that each site maps well, but that sites map the same way. Sharing mapping conventions, and where possible shared mapping tables for common local systems, reduces differences between sites.
Federation adds a useful property here. In a Trusted Research Environment deployed at each data custodian, mapping and analysis happen where the data lives, so data never leaves the source. Network coordinators can still compare mapping coverage and concept counts across sites through aggregate reports, which highlights a site whose mapping lags without anyone moving patient-level data. AI-assisted mapping can then be applied at each site under the same review rules, so that harmonization scales without centralizing records.
Who should own vocabulary mapping
Mapping sits between disciplines, and projects stall when nobody owns it. Data engineers know the source systems and the ETL, but they rarely have the clinical knowledge to judge whether a local lab code really means a particular test. Clinicians and clinical coders have that knowledge, but need a simple review interface and clear conventions. The most reliable setup gives engineering ownership of the pipeline and coverage reporting, gives a named clinical lead ownership of mapping decisions, and holds a short regular review where unmapped and disputed codes are cleared. Research users should be able to see the mapping tables, so they can check how a concept they rely on was built and raise issues when results look wrong.
Practical next steps
Start with a code inventory and a frequency count for each source. Resolve standard codes automatically, then focus clinical review on the local codes that cover the most records. Set a coverage target per domain, record every mapping decision, and rebuild your test cohorts with each vocabulary release. These habits turn vocabulary mapping from a one-off project into a maintained asset that keeps paying back with every new study.
Frequently asked questions
What is OMOP vocabulary mapping?
It is linking each source code in a dataset to a standard concept in the OHDSI vocabularies, so that analyses written once can run on any OMOP database and return comparable results.
What is a standard concept in OMOP?
A standard concept is the preferred term for a clinical idea within its domain, flagged for use in analysis. Source codes are linked to standard concepts through “Maps to” relationships.
Which tool is used to map local codes to OMOP?
The OHDSI Usagi tool is widely used. It suggests candidate standard concepts based on code descriptions, and a reviewer confirms each mapping. AI-assisted matchers can speed this up.
Where are local mappings stored?
In the SOURCE_TO_CONCEPT_MAP table, or as custom concepts with IDs above 2,000,000,000, the range reserved for local use.
How do I measure mapping quality?
Report the share of distinct codes and of records mapped to a standard concept, by domain, and run the OHDSI Data Quality Dashboard and Achilles after each build.
How often should mappings be reviewed?
With every vocabulary release and every significant change in the source system, plus whenever coverage drops in a regular quality report.