JSON Schema to TypeScript Interface — Sample-Based vs Schema-Based

JSON Schema is the formal specification language for describing valid JSON — required fields, enums, unions, pattern constraints, all of it. When you have a JSON Schema document, you can generate TypeScript types that cover every valid shape, not just the one sample you happened to paste. Our sample-based tool doesn't read schemas; here's what does and when to use which.

Sample vs Schema — What the Difference Actually Is

A JSON sample is one observation: "the API returned this on Tuesday." A JSON Schema is the contract: "the API can return any shape matching these rules."

Consider a schema fragment:

{
  "type": "object",
  "properties": {
    "status": { "type": "string", "enum": ["pending", "approved", "rejected"] },
    "approvedBy": { "type": "string" }
  },
  "required": ["status"],
  "dependencies": {
    "approvedBy": ["status"]
  }
}

The schema says: status is one of three literal strings; approvedBy is optional; if approvedBy is present, status must be too. A single sample showing { status: "pending" } tells you none of that.

The TypeScript you get from the schema:

interface Item {
  status: "pending" | "approved" | "rejected";
  approvedBy?: string;
}

Note the string literal union for status. A sample-based tool would have typed it as plain string. The tighter type prevents a whole category of bugs at compile time.

The Main Schema-Based Tools

Three tools cover the schema-to-TypeScript space well:

1. json-schema-to-typescript (bcherny/json-schema-to-typescript). A Node library and CLI. Takes a JSON Schema document and outputs a TypeScript file with one type per schema. Supports $ref resolution, which matters for real-world schemas that split across files.

npx json-schema-to-typescript schema.json -o types.ts

2. Quicktype. Also handles JSON Schema input. Less TypeScript-specific — it generates 20+ target languages from the same schema. Heavyweight if you only need TypeScript; useful if you need multi-language output.

3. openapi-typescript. Specifically for OpenAPI 3 documents (which contain JSON Schema). If your API ships OpenAPI, this is usually the best tool — it generates types for every endpoint, not just schemas.

For raw JSON Schema (not OpenAPI), json-schema-to-typescript is the dedicated choice. For OpenAPI, use openapi-typescript. For multi-language or complex workflows, Quicktype.

Sell Custom Apparel — We Handle Printing & Free Shipping

When You Don't Have a Schema

Most internal APIs, many SaaS APIs, and a notable chunk of public APIs still don't ship a JSON Schema. In that case, you're stuck with sample-based generation:

• Hit the endpoint, copy the response
• Paste into our JSON to TypeScript generator
• Tighten the output by hand for fields you know are enums or unions

The sample-based types will be looser than schema-based would be — a status: string instead of a union literal, an optional field that shouldn't be optional. But they'll match what the API actually returns, which is all you need most of the time.

For long-lived integrations, it's worth asking the API owner for a schema. Modern frameworks (NestJS, FastAPI, ASP.NET) can emit one from the code, so the cost of providing it is usually low.

Schema Features That Don't Translate to Samples

Five JSON Schema features that produce better TypeScript than any sample can:

• enum — becomes a string literal union. "a" | "b" | "c".
• oneOf / anyOf — becomes a discriminated union. A | B | C.
• required — fields not in the required list become optional. Samples can't distinguish "absent in this sample" from "truly optional."
• additionalProperties: false — closes the object type. TypeScript's default object types allow extra properties unless explicitly restricted.
• nullable / type: ["string", "null"] — produces string | null. Samples only show whichever variant happened to ship.

When any of these matter for your use case, schema-based generation is dramatically better. When they don't — you just need a type for "the shape I saw once" — samples are fine.

Practical Hybrid Workflow

Teams that use both tools typically split like this:

Explore with samples. You're trying a new API. Hit an endpoint, generate an interface from the response, poke at it, decide if the API is usable. Throwaway work.

Commit with schema (if available). You've decided to build against the API. If a schema exists, set up openapi-typescript or json-schema-to-typescript in CI. Types regenerate automatically as the schema evolves.

Validate at runtime. Compile-time types aren't enough — the API can return shapes that don't match its schema. Use Zod for runtime validation so drift fails loudly at the boundary instead of silently deep in your code.

The three tools complement each other. Sample-based for discovery; schema-based for systematic coverage; Zod for runtime safety.

Frequently Asked Questions

Does your tool read JSON Schema documents?

No. Our tool infers from sample JSON values. For schema-based generation, use json-schema-to-typescript or Quicktype.

What is the difference between JSON Schema and OpenAPI?

JSON Schema describes data shapes. OpenAPI describes full REST APIs (endpoints, parameters, responses) and uses JSON Schema internally for shape definitions.

Can I convert a TypeScript interface back to JSON Schema?

Yes, with tools like typescript-json-schema or ts-json-schema-generator. Useful when TypeScript is the source of truth and you need a schema for validation or documentation.

Which tool should I use for an OpenAPI spec?

openapi-typescript for just types. Orval if you also want a generated HTTP client. Quicktype if you also need non-TypeScript output.