Lesson 5 of 30

Schema Validation at the API Boundary

Q: Your team's frontend calls a third-party API you don't control, and last month a field silently changed from a string to a number, causing a crash deep in a formatting function far from where the data entered the app. How would you prevent this from happening again?

A strong answer covers: Explains that the TypeScript type annotation on the original fetch call provided zero runtime guarantee — it never actually checked the real response; Proposes runtime schema validation (naming Zod or an equivalent) that parses and checks the response at the point it enters the app; Explains the benefit: the failure now happens loudly at the fetch boundary with a clear error, instead of silently propagating as undefined/wrong-type data to a distant consumer; Acknowledges the real tradeoff — added runtime cost and schema-maintenance work — and connects it to why it's justified specifically here (an external API outside the team's control).

A TypeScript type on a fetch response is a promise checked once, at compile time, by a human — nothing verifies at runtime that the data actually arriving matches it, and a silent backend change slips right through.

13 min read

Check your understanding

Every option explains itself — why the right one is right, and why each wrong one is wrong. Miss one and it comes back later on a spaced-repetition schedule.

Question 1 of 3

A function is typed as `Promise<User>` and simply returns `res.json()`. The backend renames a field the type expects. What happens?

Nothing catches it at the fetch call — the missing field silently becomes undefined and the bug surfaces wherever it's later usedTypeScript throws a compile error the next time the project is builtThe fetch call itself throws a runtime error immediately

Stuck? Ask the AI tutor

Hints without spoilers, and a plain explanation of why a wrong answer was wrong — answered only from this lesson. Free account, no card.

Interview questions on Schema Validation at the API Boundary

What interviewers actually ask about this, and what a strong answer has to cover.

Your team's frontend calls a third-party API you don't control, and last month a field silently changed from a string to a number, causing a crash deep in a formatting function far from where the data entered the app. How would you prevent this from happening again?

A strong answer covers

Explains that the TypeScript type annotation on the original fetch call provided zero runtime guarantee — it never actually checked the real response
Proposes runtime schema validation (naming Zod or an equivalent) that parses and checks the response at the point it enters the app
Explains the benefit: the failure now happens loudly at the fetch boundary with a clear error, instead of silently propagating as undefined/wrong-type data to a distant consumer
Acknowledges the real tradeoff — added runtime cost and schema-maintenance work — and connects it to why it's justified specifically here (an external API outside the team's control)

Likely follow-ups

Would you recommend the same runtime validation for calls between two internal services your own team owns and deploys together? Why or why not?
What would you do at the call site if the schema validation throws — how should the rest of the UI react?

The plain-language idea

Writing const data: User = await response.json() doesn't check anything. TypeScript trusts that type annotation completely and never looks at it again once compilation finishes — there's no code running at runtime that confirms the JSON that actually arrived has the fields, types, or shape the annotation claims. If a backend renames a field, makes a field that used to always be present now sometimes missing, or changes a field from a string to a number, TypeScript will not catch it, because TypeScript never runs against the real response at all.

The fix is runtime schema validation: a library that actually parses the raw response data and checks it against a schema while the program is running, throwing or returning a typed error if the real shape doesn't match what was expected. This repo's own codebase already uses Zod for exactly this purpose — it's a concrete, reasonable library to name when this comes up, though the same idea applies to any runtime validation library.

See it in a real thing: parsing instead of asserting

// Compile-time-only "safety" — this is just an assertion, not a check
async function getUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  return res.json(); // TypeScript trusts this is a User. Nothing verifies it.
}

import { z } from "zod";

const UserSchema = z.object({
  id: z.string(),
  email: z.string(),
  displayName: z.string(),
});

type User = z.infer<typeof UserSchema>;

async function getUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  const raw = await res.json();
  return UserSchema.parse(raw); // actually checked against the real response, at runtime
}

If the backend renames displayName to name tomorrow, the first version keeps compiling and keeps "working" — every consumer of user.displayName silently gets undefined, and the bug surfaces wherever that value happens to get rendered or used, possibly far from the actual fetch call. The second version fails loudly, at the fetch call itself, with a clear message about exactly which field didn't match — the moment the contract breaks, not sometime later downstream.

What people usually miss

Watch out

TypeScript types and runtime schemas are solving different problems, not competing. TypeScript's type-checking happens once, at build time, against the code you wrote. A runtime schema checks the actual data your code receives, every single time it receives it. Neither one substitutes for the other.
Runtime validation has a real, if usually small, cost — it's not free. Parsing and checking every response's shape does take actual CPU time and adds a real dependency; this is a genuine tradeoff, not a reason to skip it, but it's honest to name.
The strongest case for it is specifically at trust boundaries. An external API you don't control, or a backend team that ships independently of the frontend and can change a response shape without the frontend knowing in advance, are the situations where a silent contract break is a real, recurring risk — not necessarily every single internal, tightly-coupled function call where both sides are already guaranteed to stay in sync.
A missing field doesn't throw a JavaScript error on its own — it just becomes undefined and propagates. Without runtime validation, accessing a property that no longer exists on the response doesn't crash where the bad data entered the app; it silently becomes undefined and often crashes (or worse, silently misbehaves) somewhere unrelated and much harder to trace back.

Why this matters in interviews

"How do you guard against a backend response shape changing unexpectedly?" is a real, common question, and naming runtime schema validation specifically (not just "we have TypeScript types") — plus being able to articulate that TypeScript types alone provide zero runtime guarantee — shows a candidate understands the actual gap between compile-time and runtime safety, not just that a validation library exists.