DOCUMENTATION / API COMPATIBILITY

Why a TypeScript build can pass after an API changes.

By Soumik Ghosh · Published 3 November 2026

A TypeScript type assertion describes what your code assumes. It does not validate data arriving from a remote API at runtime. If an upstream field disappears, code can still compile against an unchanged local interface.

Why does a response cast still compile?

type Result = { message: { content: string } };
const result = (await response.json()) as Result;
show(result.message.content);

This synthetic example asserts a shape without checking it. If the response no longer includes message, the final read can fail at runtime. A generated SDK can improve type information, but the installed version and actual service contract still need to agree.

The TypeScript handbook explains that type assertions are removed by the compiler and do not add runtime checking.

What can contract and call-site analysis add?

A captured schema diff identifies changed guarantees. Supported static usage mapping narrows the search to affected calls at a specific commit. Dynamic payloads, wrappers, reflection, and unmatched patterns can still need manual review. A matching call is evidence to inspect, not proof that every code path was analyzed.

What belongs in validation?

1. Validate external data against the runtime schema your application requires.
2. Run type checks against the complete candidate.
3. Exercise representative responses and missing-field behavior in your tests.
4. Inspect the proposed edit, available runtime evidence, and repository CI before merging.

See a captured optional response field and compare schema acceptance directions.