Who this is for¶
Crosswalk assumes you are capable and busy, and that nobody gave you a runway. Most people arrive at FHIR to OMOP work sideways: a grant gets funded, a data use agreement gets signed, a vendor turns on an endpoint, and suddenly the transformation is your problem.
There are three common starting points, and the site is built so each one has a sensible path.
You arrived from the FHIR side¶
You know what a resource is. You have written a search query and read a CapabilityStatement. What you do not have is a feel for why researchers keep asking for something other than what you already give them.
Your path: Skip lightly over what FHIR actually is, then slow down considerably at what OMOP actually is and concepts and domains. The vocabulary layer is the part FHIR practitioners consistently underestimate, because FHIR treats terminology as a binding on a field and OMOP treats it as the organizing principle of the entire model.
The idea that will reorient you: In OMOP, the code decides which table the row goes in. Not the resource type. The code.
You arrived from the OMOP side¶
You have built cohorts in ATLAS. You know what a concept set is and you have argued with someone about whether a code belongs in it. What you do not have is a feel for why the incoming data is shaped so strangely.
Your path: Skim what OMOP actually is as a refresher, then spend real time in what FHIR actually is and reading a bundle out loud. The thing OMOP practitioners consistently underestimate is how much of a FHIR resource is optional, how much variation two conformant servers can show, and how much of the meaning lives in profiles rather than the base specification.
The idea that will reorient you: A FHIR server is not a database export. It is an answer to a question, shaped by what the asking system was built to say.
You arrived from neither¶
You are a physician researcher, a graduate student, a program officer, or a project manager. You need to understand this well enough to make good decisions, ask sharp questions, and know when an answer is hand-waving.
Your path: Read the site in order, start to finish. Do not skip the ten-minute orientation; it gives you a frame that keeps the later detail from feeling arbitrary. Use the workbook if you want the material to be durable rather than temporarily clear.
The idea that will reorient you: Nobody fully understands both models. The experts you are working with each know one side deeply and the other side approximately. Your questions are more valuable than you think.
What you do not need¶
You do not need to write code to get value from this. Roughly two-thirds of the material is conceptual and applies whether you are building the pipeline, reviewing it, funding it, or relying on its output.
You do not need a database. The examples use small synthetic bundles you can read in a text editor, and the interactive tools run entirely in your browser.
You do not need to have used ATLAS, Athena, or Usagi. The vocabulary chapter introduces them from zero.
What it admits to¶
This transformation involves real judgment calls where reasonable practitioners disagree. Where that is true, the site says so and presents the options rather than pretending there is one right answer. The places where the community has genuinely converged are marked differently from the places where local convention still rules.
That distinction is useful to you in a specific way: when you document your pipeline, the settled decisions need a line and the unsettled ones need a paragraph explaining what you chose and why.