JSON Schema Generator

JSON Schema vs TypeScript types — why both still matter in 2026

TypeScript types are a compile-time tool: they vanish at runtime. JSON Schema is a runtime contract: it is data that can be passed across services, embedded in OpenAPI documents, used to drive form generation, and validated against actual payloads. The two are complementary, not redundant.

When a backend Node.js service receives a request, TypeScript can guarantee that internal calls match types — but only after the request is parsed and trusted. The boundary between the network and the running process is exactly where JSON Schema (or Zod, which is essentially JSON-Schema-shaped) earns its keep: parse the body once, validate it against the schema, and only then hand the typed object to your business logic. Skipping that step turns TypeScript into theatre — the compiler thinks the data is `User` but the runtime received `null`.

This tool gives you both at once: infer JSON Schema for the runtime contract, then export TypeScript interfaces for the compile-time types. They stay in sync because they come from the same samples. If your codebase already uses Zod for validation-and-types in a single source, the Zod export does the same job with a different ergonomics tradeoff. The point is that TypeScript by itself is not validation, and that JSON Schema (or its equivalents) is what stops bad data from becoming bad behavior.

Draft 2020-12 vs Draft 7 — what actually changed

Most JSON Schema generators in the wild still emit Draft 7 because that is what their validator understood when they were written. Draft 2020-12 is the current published version and brings several improvements that matter when you are designing real schemas.

The biggest change is `prefixItems` for tuple-shaped arrays. In Draft 7 you wrote `items: [schema1, schema2]` to mean “the first item must match schema1 and the second must match schema2.” In 2020-12, that syntax was retired in favor of `prefixItems: [schema1, schema2]` with `items` reserved for the “rest” schema. The renaming clears up an ambiguity that confused validators and humans alike.

The `$defs` keyword (replacing the older `definitions`) is now part of the official vocabulary, which means tooling can reliably detect reusable subschemas without relying on convention. Boolean schemas (`true`/`false` as a complete schema) are formalized: `{ ...properties, additionalProperties: false }` and `{ ...properties, additionalProperties: { type: ... } }` work as you expect.

When should you stay on Draft 7? If your validator runtime cannot upgrade — for example, an older Java validator pinned to a specific dependency — you have to match that version. OpenAPI 3.1 aligns with Draft 2020-12; OpenAPI 3.0 uses a Draft 4-flavored subset. This generator targets 2020-12 by default but lets you switch with a single setting; the inference is the same, only the rendering changes.

Why multi-sample inference produces strictly better schemas

Inferring a schema from one sample is fast but always gets two things wrong. First, it cannot distinguish optional properties from required properties — every key in the sample looks required, even though many are not. Second, it cannot distinguish a constant value from a representative value — a single `"status": "active"` becomes `type: string` even when the real domain is an enum of three values.

Multi-sample inference fixes both. With three or more samples, a property is required only if it appears in every sample (intersection), so optional fields automatically end up outside the `required` array. With repeated values, the engine collects all observed values for each field and emits an `enum` when the cardinality is small (default ≤ 8). Type conflicts across samples — say, a field that is `string` in one sample and `null` in another — emit `oneOf` or `anyOf`, surfacing the union explicitly instead of silently picking one.

The practical advice: when you generate a schema for a real API, do not just paste the happiest example. Paste 3–5 representative payloads: an empty array, a record with optional fields populated, a record where a discriminated union takes a different branch, a record with a null where a value is allowed. The schema you get is one you can actually trust at the boundary of your service. A single-sample schema is a starting point; a multi-sample schema is a contract.

When to extract repeated subschemas as $defs

Inline schemas are easier to read at first glance; $defs schemas are easier to maintain. The right tradeoff depends on how often a subshape repeats and how likely it is to evolve.

If an Address shape appears once in a User object, leaving it inline is correct — extracting it adds indirection without simplifying anything. If the same Address shape appears in User, Order, and Invoice, extracting it once and using `{ "$ref": "#/$defs/Address" }` three times reduces duplication and ensures that when Address gains a `country_code` field, you update one place. The default threshold in this tool is 2+ uses; if you prefer a more conservative output, raise it to 3+.

There is a second consideration: the consumer of the schema. Some validators and codegen tools handle `$ref` flawlessly; some struggle with deeply nested or recursive `$ref`. If you are generating TypeScript via a codegen tool that does not support `$ref`, extraction will produce types you cannot consume — set the threshold to “never” and accept the duplication. The tool also automatically handles cycle detection: a schema that would otherwise refer to itself infinitely (a Tree node whose children are Tree nodes) becomes a `$ref` automatically, regardless of the threshold setting.

Format detection is conservative on purpose

The `format` keyword in JSON Schema is one of the most misused features. The spec says formats are advisory — validators may or may not enforce them — and the precise definition of each format varies. AJV with `ajv-formats` enforces a strict version of each: `email` follows RFC 5322 lite, `date-time` follows ISO 8601 / RFC 3339, `uuid` requires hyphenated lowercase. If your data does not match the strict spec, validation fails even though the data looks fine to a human.

The inference engine in this tool is conservative for exactly that reason. A format keyword is emitted only when every observed value of a property matches the strict format spec. One value with a typo, one value using a non-standard email shape (e.g., display-name notation), one date in `M/D/YYYY` rather than `YYYY-MM-DD`, and the format keyword is dropped — the property remains a plain string. This avoids the worst failure mode: a schema that AJV rejects against the same input it was generated from.

If you want a format that the engine refused to emit, set it manually after generation. The output editor accepts direct edits and revalidates against your samples in real time. If you also want to relax the strictness, switch to a draft (4 or 6) where many formats are not validated by default — but be aware that you are giving up the runtime guarantee in exchange for a more lenient schema.