Stop Schema Drift - The Easy Way to Sync Your backend openAPI and React Frontend with Zod

Schema drift is one of those problems that sneaks up on you. Everything works fine on day one, then weeks later, production breaks — and you have no idea why.

Everything looks clean at first. Your backend defines an API contract. The frontend reads it. TypeScript is happy, Zod is validating, and you move on to actual work. Then a few weeks later, things break. Maybe the backend added a new value to an enum. Or a field that was optional suddenly became required. A small change in a nested object somewhere. You didn't hear about it.

I've been there myself. Built a Python backend with OpenAPI specs and a React frontend with Zod validation. In theory, everything was type safe. In practice? Two completely different systems trying to say the same thing — but slowly drifting apart.

Where Things Started to Fail

Early on, I manually wrote TypeScript types and matching Zod schemas on the frontend. It worked — for a while. But it relied on discipline. Every backend change meant a frontend change, and let's be honest, that didn't always happen.

It felt safe, but it wasn't. TypeScript catches errors at compile time — that's great until your app is running in production and something slips through. Zod helped validate data at runtime, but only if the schemas were actually correct. And when they fell out of sync, Zod couldn't help.

Enums were the worst part. Add a new value on the backend, and the frontend immediately breaks. And enums matter — they're used for roles, statuses, permissions. Business logic depends on them.

Rethinking the Approach

So I tried something different. Instead of chasing sync, I removed the problem entirely. The backend already had an OpenAPI schema — that's the contract. So rather than duplicating it on the frontend, I made everything derive from that single source. If the backend changes, the frontend adapts automatically — or the build fails immediately. No guessing.

Turning OpenAPI into the Foundation

First step: treat the OpenAPI schema as the source of truth. I used openapi-typescript to generate TypeScript types directly from the backend schema. No more assumptions — the frontend just consumes what the backend actually provides.

This improved things, but it didn't solve runtime validation. That's where Zod still mattered.

Bridging Compile-Time and Runtime

Here's the catch: TypeScript types disappear at runtime — they're gone once the code compiles. Zod runs at runtime and validates actual data. The challenge was linking them without duplicating work.

The fix: define Zod schemas that match the generated TypeScript types exactly. Now if something's off, you catch it during development — not in production. That's tight coupling, but in a good way. Change the backend schema, the types change too. An incompatible Zod schema simply won't work.

Solving the Enum Problem Properly

Enums needed special treatment — they caused most of the problems. Hardcoding enums in Zod schemas was just asking for drift. The backend keeps evolving, the frontend stays frozen.

So I created enums once and reused them everywhere. The Zod schema consumed what TypeScript already defined. No duplication, no repeating values.

What this gave me:

• TypeScript inferred the right union type
• Zod validated against the same values
• Backend changes propagated immediately
• No duplication, no mismatch, no surprises

Automating the Entire Flow

The real value of this approach comes from automation. Manually generating types defeats the purpose, so I wired the process into the build pipeline.

Just an npm script that pulls the OpenAPI schema and generates types. It runs during development and as part of the container build. Every new image: pull the latest schema, regenerate types, validate the frontend.

If something doesn't match, the build fails. That's the key shift. Catch issues at build time, not in production. The system enforces itself.

What Changed After This

The payoff was immediate. The frontend stayed in sync automatically — no more reminding people to update types or schemas. The workflow just worked. And since Zod was still in the mix, runtime validation stayed solid.

The big win was confidence. I knew data would match the backend contract when it reached the frontend. Not because I'm careful — because the system guarantees it.

Trade-offs and Realities

Obviously, there are trade-offs. Writing Zod mappings still takes effort, especially for complex schemas. And this whole thing depends on the backend's OpenAPI spec being correct. If the schema is wrong, everything breaks.

There's also a build-time dependency on the backend. You might need to cache schemas or version them to avoid random build failures from network issues.

But these are manageable. Way easier to deal with than production bugs from schema mismatches.

Final Thoughts

The biggest lesson wasn't about the tools — Zod, OpenAPI, none of that. It was about removing ambiguity. Manually keeping frontend and backend in sync is a losing battle as systems grow. Define a single source of truth, and let everything else derive from it.

Once you do that, sync isn't a task anymore — it's a property of the system. In headless CMS setups or dynamic schema-driven platforms, it's not optional. It's essential.