Recommended Free Tools
A TypeScript type does not validate JSON at runtime. When an application consumes an API it does not control, treat the response as unknown, check the fields the application needs, and return a typed value only after those checks pass. For a small contract, a focused parser can make failures clear without adopting a schema library; for complex or shared schemas, Zod may be the better fit.
How do I validate an API response in TypeScript?
Keep three separate boundaries visible: the HTTP response, JSON decoding, and validation of the decoded value. Each can fail for a different reason, so handle them in that order.
As an Amazon Associate I earn from qualifying purchases.
- Check the HTTP status. A resolved
fetch()promise does not mean the server returned a successful status. MDN explains that an HTTP error such as 404 still fulfills with aResponse; checkresponse.okbefore treating the response as successful. See MDN’s Fetch API guide. - Decode the body. Call
response.json()and handle decoding errors. A response with invalid JSON cannot be parsed into a JavaScript value. - Validate the application shape. Valid JSON may still be a string, array, missing required fields, or contain values of unexpected types. Pass the decoded value to a boundary parser that accepts
unknown.
For example, this pattern checks a small user resource. Replace the endpoint and fields with the contract your application actually consumes; the example is illustrative, not a claim about a particular API.
Free tools Windows power users keep installed
One-click scans. No signup required.
type User = {
id: string;
name: string;
};
function parseUser(value: unknown): User {
if (typeof value !== "object" || value === null || Array.isArray(value)) {
throw new Error("GET /api/user: expected an object");
}
const record = value as Record<string, unknown>;
if (typeof record.id !== "string") {
throw new Error("GET /api/user: expected field 'id' to be a string");
}
if (typeof record.name !== "string") {
throw new Error("GET /api/user: expected field 'name' to be a string");
}
return { id: record.id, name: record.name };
}
async function getUser(): Promise<User> {
const response = await fetch("/api/user");
if (!response.ok) {
throw new Error(`GET /api/user failed with HTTP ${response.status}`);
}
const body: unknown = await response.json();
return parseUser(body);
}The parser checks the enclosing structure before reading properties, verifies each required field’s runtime type, and constructs a fresh domain value. Returning only the fields the application needs also keeps arbitrary response data out of downstream code. In production, include resource or endpoint context in errors where useful, but avoid logging credentials or dumping a complete response that may contain sensitive data.
#1 Best Overall
Can I trust a TypeScript type for JSON returned by an API?
No—not by itself. A declaration such as const user: User = await response.json() tells the compiler what to assume; it does not inspect the bytes received from the server or prove that the object has those fields. Network data crosses a runtime boundary, so its shape must be checked before it is treated as a trusted domain value.
TypeScript’s handbook recommends unknown when a value could be anything, then narrowing it through checks before use. That is the right mental model for decoded JSON: begin with unknown, validate the needed facts, and let the parser’s return type describe what has actually been established. See Microsoft’s TypeScript Handbook: Basic Types.
Rank #2
- TypeScript implements a superset of syntax for strictly typed development, facilitating deep static analysis and enhanced development environment integration. The compiler translates source into standard script formats, ensuring parity across any runtime.
- TypeScript is ideal for front-end developers, full-stack engineers, and software architects who build large-scale web applications. It serves those looking to improve code excellence, reduce bugs through static checking, and maintain complex projects more.
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
How do I make an API parser fail loudly when the response changes?
Make required-field checks explicit and errors actionable. A useful error identifies the resource or endpoint and the field and expected type, rather than saying only “invalid response.” This helps distinguish a server-side contract change from a transport problem or malformed JSON.
- Check that the top-level value has the expected container shape before accessing fields.
- Check required properties individually and report the first invalid field, or collect structured issues if the application needs to display several at once.
- Keep malformed required fields distinct from additional unknown keys. An extra field is not automatically a breaking change; rejecting all additions can make an otherwise compatible API extension fail.
- Do not include secrets or the entire payload in diagnostic messages. Field names and expected types are usually enough to locate the mismatch.
“Fail loudly” should mean failing at the boundary with enough context to fix or investigate the mismatch—not allowing invalid data to travel deeper into the application, and not producing an opaque crash later.
When should I use Zod instead of writing a parser?
Zod is a reasonable choice when runtime validation is recurring, the contract has nested structures or several variants, or schemas need to be shared across multiple boundaries. It connects runtime parsing with inferred TypeScript types. Zod describes itself as a TypeScript-first validation library and documents support for Node.js and modern browsers, zero external dependencies, and a 2 KB gzipped core bundle; the size is the project’s own published claim, not an independent benchmark. See Zod’s introduction.
A hand-written parser can be an appropriate choice for a small, focused contract when direct checks and tailored error messages fit the surrounding code. That is a design trade-off, not evidence that handwritten code is inherently faster, smaller, safer, or easier to maintain. Choose based on the contract and the project’s needs, not an assumed performance advantage.
| Decision factor | Focused hand-written parser | Zod schema |
|---|---|---|
| Contract complexity | Fits a small number of straightforward fields and checks. | Can express nested schemas, unions, optional variants, refinements, and transformations. |
| Error behavior | You control the wording and context; you must implement and maintain the checks. | Provides schema-based parsing errors; tailor handling to the application’s needs. |
| Type relationship | The function’s declared return type can represent the validated domain value; keep the checks and type aligned. | Parsed results can provide types inferred from the schema. |
| Maintenance | Consider whether checks duplicate types and how often the external contract changes. | A schema can be a single validation-and-type source, though it still needs maintenance as the contract changes. |
| Unknown keys | Choose deliberately whether to ignore, preserve, or reject additional properties. | z.object() strips unknown keys by default; z.strictObject() rejects them. See Zod’s API documentation. |
| Dependencies and reuse | May suit a one-off boundary where a project-specific library is not needed. | May suit teams already using Zod or validating the same kinds of data at several runtime boundaries; whether adding it fits a project’s dependency policy is project-specific. |
What should you do with unknown fields?
Decide whether additive fields are compatible with your application. If it consumes only a few known fields, ignoring or stripping extras can let the API add data without breaking the client. Reject extras when the contract requires an exact shape or when unexpected keys indicate a meaningful risk; do not make strictness an accidental side effect of the parser.
Zod’s defaults make this distinction concrete: z.object() strips unrecognized keys, while z.strictObject() rejects them. Required schema fields are required unless made optional. Check the library’s object API documentation when selecting behavior.
Best Value
A practical rule for the boundary
Use unknown for data you have not validated. Separate HTTP failure, JSON decoding failure, and contract failure. Then choose the simplest validation approach that gives your application the needed type relationship, error context, unknown-key policy, and maintainability. A focused parser is a legitimate engineering choice for a narrow contract; a schema library is often more suitable when complexity or reuse grows.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
