How JSON Schema and TypeScript types catch different bugs

By ToolSura DevTools Team, Senior Engineers · View profile

The JSON Schema vs TypeScript types debate ends once you see what each guard can know. TypeScript's handbook chapter on everyday types covers the static half; on the runtime half, Ajv can emit standalone compiled validators, and schema-first libraries like TypeBox generate one artifact that serves as both.

The core difference: compile time versus runtime

TypeScript types describe what your code believes about data while you write it. The compiler checks those beliefs across every call site, then erases them: the TypeScript handbook documents that types vanish entirely from emitted JavaScript. JSON Schema, specified at json-schema.org and introduced gently in its getting-started guide, is a validation document that runs against actual data whenever you invoke a validator.

That timing difference decides everything. Types protect the world you control: your functions calling each other with the shapes you promised. Schemas protect the world you do not: HTTP payloads, config files, queue messages, anything that crosses a trust boundary as bytes rather than as compiled code.

Proof by crash: the same payload through both guards

During research for this guide we ran a small but decisive experiment. A TypeScript file declared a User type, parsed hostile JSON from a string pretending to be a network response, asserted it with a cast, and called string methods on fields typed as strings, shown here alongside the payload that broke them:

type User = { id: number; email: string };
const payload = JSON.parse('{"id": "abc", "email": 42}');
const user = payload as unknown as User;
console.log(user.email.trim());

The equivalent JSON Schema document, the one Python's jsonschema later enforced, declared "properties": {"id": {"type": "integer"}, "email": {"type": "string"}}, "required": ["id", "email"]. Environment details for anyone reproducing the run: tsc 5.3.3, Node v22.22.2, jsonschema 4.26.0.

tsc compiled this without a single warning. Running the output in Node produced:

TypeError: user.email.trim is not a function

The type system believed whatever the cast said and vanished at the moment of truth. We then validated the identical payload against an equivalent JSON Schema using Python's jsonschema library, which rejected it immediately with precise diagnostics:

ValidationError: 'abc' is not of type 'integer' (at id)
ValidationError: 42 is not of type 'string' (at email)

Python's jsonschema library, version-pinned above, produced those diagnostics; any conforming validator returns the same verdict for this schema.

Same data, opposite outcomes. Neither tool failed; each was asked only what it can answer. The compiler checks beliefs between your own lines of code, where casts are trusted. The schema inspects values arriving from outside, where nothing deserves trust.

JSON Schema vs TypeScript types: coverage compared

Guard coverage compared

Concern	TypeScript types	JSON Schema
Catches typos inside your codebase	Yes, exhaustively	No
Validates incoming API payloads	Only if data was checked first	Yes, at runtime
Survives into production JavaScript	No, erased at build	Yes, plain data
Consumable by non-TypeScript services	No	Yes, language-neutral
Generates documentation or forms	Only through generated docs or codegen	Naturally
Refactoring support	Precise, IDE-driven	Manual schema edits

Using both without duplication

Teams rarely choose one; they wire the two together so truth lives once. Schema-first stacks generate TypeScript types directly from JSON Schema, keeping the compile-time view derived from the runtime contract rather than drifting from it. Code-first stacks go the other way, emitting schemas from zod declarations, whose authors document exactly this pattern at zod.dev. Validators such as Ajv execute JSON Schema inside JavaScript at high speed, closing the runtime gap inside TS projects themselves.

The anti-pattern worth naming: hand-maintaining parallel definitions that slowly disagree. If your type says email is a string and your schema forgot to require it, the bug lives in the gap. Generation from one source of truth removes the gap class entirely; the compiler overview in the handbook explains what emission erases.

Where each belongs in a real stack

• Validate every untrusted input with JSON Schema at the boundary, before any cast exists
• Let TypeScript carry certainty inward from there, unchecked casts banned in review
• Keep schemas as published contracts for partner teams and public APIs, since the specification is deliberately implementation-neutral
• Preview and iterate on contracts with the JSON schema generator, and inspect payload shapes during debugging with the JSON formatter
• For the schema format itself beyond the comparison, our what-is-json-schema guide walks the keywords field by field using examples from the official getting-started guide

Two locks on two different doors

JSON Schema vs TypeScript types is a false rivalry once the experiment runs: one guards your code's internal consistency until build time, the other guards reality's bytes forever after. Compile-time confidence cannot inspect a network response, and a runtime validator cannot refactor your call sites. Put the schema at every boundary, let types rule everything behind it, and generate one from the other so the story never splits.

Related Tools

• JSON Diff Compare
• JSON Schema Generator