An API response can arrive as valid JSON and still be the wrong shape. A field may be missing, a number may become a string, or an upstream error may use a different response body.

In TypeScript, asserting a type does not inspect that response:

1
2

type Shipment = { id: string; delayDays: number };
const shipment = (await response.json()) as Shipment;

The assertion tells the compiler what to assume. It does not establish that the server returned those fields.

Check the boundary

For a small value, the check can be explicit:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

function isShipment(value: unknown): value is Shipment {
  if (typeof value !== "object" || value === null) return false;
  return (
    "id" in value && typeof value.id === "string" &&
    "delayDays" in value && typeof value.delayDays === "number" &&
    Number.isFinite(value.delayDays)
  );
}

if (!response.ok) throw new Error("Shipment request failed");
const payload: unknown = await response.json();
if (!isShipment(payload)) throw new Error("Unexpected shipment response");

This validates only the contract shown. It does not decide whether a negative delay is meaningful or whether the identifier belongs to the current user. Those are separate domain and permission checks.

For larger schemas, a runtime validation library may make the contract easier to maintain. The important point is where the evidence comes from: a check that runs on the incoming value, not an assertion that disappears when the code is compiled.

Once the value passes that boundary, static types are useful for keeping the rest of the application consistent. They help prevent an internal caller from accidentally passing the wrong structure. Runtime validation and static checking support different parts of the same path.

Reference: TypeScript handbook: narrowing and type predicates.