Reading list¶
Everything below is free unless marked otherwise. The list is short on purpose. A person learning this transformation does not need forty links, they need six good ones and a sense of what each is for.
Read these first¶
The Book of OHDSI¶
The community textbook for OMOP and the OHDSI methods ecosystem, available free online and in print. Chapters 4 through 6 cover the common data model, standardized vocabularies, and extract-transform-load, which is the part of the book this site assumes you have either read or are about to.
Read it for: the canonical description of what each OMOP CDM table holds and why. When this site and the Book of OHDSI disagree on a definition, the Book is right and I would like to hear about it.
The FHIR specification, R4¶
The specification itself is more readable than its reputation suggests, particularly the resource pages. Each resource has a scope-and-usage section, a table of elements, several worked examples, and a set of notes on boundaries with other resources. Those boundary notes are unusually good and they answer many of the questions that come up in mapping.
Read it for: what a resource is actually permitted to contain, which is often broader than what your source system puts in it.
US Core Implementation Guide¶
The profile set most United States FHIR endpoints conform to, and the one behind the certification requirements that made those endpoints exist. It tells you which elements are required, which are must-support, and which value sets bind where.
Read it for: knowing what you can safely assume is present. If US Core marks an element must-support and your source omits it, that is a conversation to have with the source.
The HL7 FHIR to OMOP Implementation Guide¶
The standard being written for exactly this transformation, developed through the Vulcan accelerator in collaboration with OHDSI. Edition 1 published as informative in April 2026, and a version went to ballot in the September 2026 cycle following testing at the July connectathon.
Read it for: the community's current answer to the questions this site raises. Where the guide is specific, follow the guide. Where it leaves room, the chapter on the IG and how to shape it explains how to say so during the comment period.
Reference you will keep open¶
Athena¶
The OHDSI vocabulary browser. You will use it constantly and mostly for three things: finding whether a source code has a standard concept, finding what domain that concept carries, and reading the relationship list to understand how a concept connects to others.
The chapter on Athena and Usagi covers how to read a concept page without being misled by the parts that look more authoritative than they are.
The OMOP CDM specification site¶
The table and column definitions, with the required, primary key, and foreign key status of each field, plus notes on conventions. Shorter than the Book of OHDSI and better for looking one thing up.
Keep it open when you are building a mapping specification, because the required columns are not always the ones you expect and the conventions notes carry decisions you would otherwise make yourself.
Usagi¶
The OHDSI tool for mapping source codes to standard concepts with human review. It suggests, you decide, and it records the decision along with your confidence.
The important thing to know before you install it is that it is a review tool rather than an automation tool. The chapter on Athena and Usagi covers working through codes in frequency order, which is the difference between a week of work and a month of it.
When you get to quality¶
Data Quality Dashboard¶
The OHDSI package that runs several thousand checks against an OMOP CDM instance and organizes the results by category. It is the tool a collaborating site will most likely ask you to run.
The chapter on proving it worked covers reading a failure back to the mapping decision that caused it, which is the skill the tool assumes and does not teach.
Achilles¶
Database characterization rather than quality checking. It produces distributions and counts across the instance, which is how you notice that something is wrong in a way no rule-based check would catch. A drug whose exposure counts drop to zero in a particular month is a pipeline problem, and no individual row in that month is invalid.
For the wider argument¶
OHDSI community materials¶
The OHDSI forums, the weekly community calls, and the working group pages. The forums in particular are searchable and full of people who hit your exact problem in 2019 and wrote down what they did. OHDSI education collects the tutorials and the EHDEN Academy training.
If you are working on a rare condition, the community is the fastest route to finding whether anyone has already built the vocabulary work you are about to build.
The Vulcan accelerator¶
The HL7 accelerator program through which the FHIR to OMOP work runs, alongside other clinical research and FHIR alignment efforts. The chapter on the IG and how to shape it covers how to participate.
Worth knowing exists¶
Bulk Data Access Implementation Guide. The specification behind the export operation, covering how a request is made, how a server responds asynchronously, and what the manifest contains. Read it before your first export negotiation rather than during it, and see getting the data for the seven questions to ask the server owner.
SQL on FHIR. A specification for defining flat, tabular views over FHIR resources using view definitions. It solves a related problem to the one this site covers, and it is a reasonable intermediate layer between raw NDJSON and OMOP CDM tables for teams who want the flattening logic to be portable and declarative rather than embedded in pipeline code.
Synthea. A synthetic patient generator that produces FHIR bundles at whatever scale you want. It is the right way to build and test a pipeline before you have access to real data, and it is the right way to make an example you can share publicly. Synthetic data has its own distributions and does not substitute for validating against your real source, but it gets you to a working pipeline much faster.
What is not on this list¶
There is no book that covers this transformation end to end. If there were, this site would be shorter. The material is spread across a specification, a textbook, an implementation guide in progress, a vocabulary browser, and the accumulated practice of people who have done it, which is most of the reason a resource like this one is useful at all.
If you find something good that belongs here, the repository takes issues.