Crosswalk¶
FHIR to OMOP, one field at a time.
You were handed a FHIR endpoint and a research question in the same week. Somebody said the words "just ETL it into OMOP" as though that were a small thing. This site is for that moment.
Crosswalk teaches the transformation from HL7 FHIR to the OHDSI OMOP Common Data Model as a set of decisions rather than a lookup table. Every decision has the same three parts: what the source says, what the target needs, and what is lost, gained, or assumed in between. That third part is the one that turns a person who can run a script into a person who can defend a design.
Three ways in¶
-
I have twenty minutes
Watch the overview video or read the ten-minute orientation. You will come out able to follow the conversation and ask useful questions.
-
I have to build this
Read the site in order, starting with what FHIR actually is. Six to eight hours gets you to working knowledge with a running example you will recognize by the end.
-
I want it to stick
The printed workbook takes the same material one page a day for six weeks, with space to draw the models yourself. Slow beats fast for durability.
What makes this different¶
One running example throughout. A synthetic person named R. Alvarez appears in every lesson. Their bundle is deliberately imperfect: a year-only birth date, an Encounter hierarchy that does not resemble a visit, a laboratory result whose code routes somewhere surprising, a local code with no standard mapping, and a medication recorded three different ways. Each imperfection is the teaching point for a specific lesson, so the case gets less mysterious as you go.
The quiet losses are named. Most transformations lose something. Temporal precision, negation, provenance, units, and clinical context all have places where they can slip away without an error message. Each lesson has a section that names exactly where.
The standard is treated as live. The HL7 Vulcan FHIR to OMOP Implementation Guide is an active piece of work, not a finished artifact. The standard chapter explains how to read it and how to contribute to it, because the people doing this work are the people whose experience should shape it.
The five tools¶
Interactive practice, free, no account, nothing leaves your browser.
| Tool | What it does |
|---|---|
| Resource Router | Give it a FHIR resource and a code, and reason through where the row belongs |
| Domain Detective | Practice the routing rule that surprises everyone, with immediate feedback |
| Field Mapper | Fill-in-the-blank mapping drills across six OMOP CDM tables |
| Bundle Reader | Paste a FHIR bundle and get a structured walk-through of what it contains |
| ETL Decision Log | Record and export the assumptions your pipeline is making |
Where to start if you are honest about being lost¶
Go to words that mean two things. A surprising amount of early confusion in this work is not conceptual difficulty. It is two communities using the same English word for different ideas, and nobody stopping to say so.
About this resource
Crosswalk is built and maintained by Danielle Boyce at Boyce Data Science. It is free, open, and community-improvable. Corrections and additions are welcome through the repository. The companion guide and workbook are paid products that support continued maintenance of the free material.
The OHDSI community¶
The OMOP CDM is not a specification handed down by a vendor. It is maintained by the OHDSI community, an open collaborative of researchers, clinicians, and engineers, and the model changes through proposals that community discusses in public. If you are building one of these pipelines you are already part of that, whether or not you have posted anything yet.
Where to go:
| Resource | What it is for |
|---|---|
| OHDSI | The community itself, including weekly community calls and the working groups |
| The Book of OHDSI | The community textbook, free online. Chapters 4 through 6 cover the OMOP CDM, the vocabularies, and ETL |
| OMOP CDM specification | Table and column definitions, with required status and conventions. The v5.4 pages are the current reference |
| OHDSI Forums | Searchable, and full of people who hit your exact problem years ago and wrote down what they did |
| Athena | The vocabulary browser you will keep open while mapping |
| OHDSI software tools | ATLAS, Usagi, the Data Quality Dashboard, Achilles, and the rest |
| OHDSI education | Tutorials and training, including the EHDEN Academy |
If you are working on a rare condition, the forums and the working groups are the fastest route to finding whether somebody has already built the vocabulary work you are about to build.