Quicktype Compatibility Guide

Quicktype choking on your schemas?
Fix the source spec first.

Quicktype generates types — TypeScript, Effect Schema, Zod, Go, and more — from JSON Schema and OpenAPI components. When the output is wrong or generation fails, the cause is almost always in the input schemas. Validate your spec here and see exactly what to fix.

Why does Quicktype produce wrong types from a "working" API spec?

Quicktype infers types from what the schema says, not what your API does. If a schema marks a field required but the API returns null, or a $ref silently resolves to nothing, the generated Effect Schema / Zod validators will reject real responses — or Quicktype fails to generate at all. Cleaning up the source schemas is the fix; a strict validator shows you every inconsistency with line numbers.

The 4 schema problems that break Quicktype output most often

1. Required vs nullable disconnect

A field sits in the required array while its type allows null — or is nullable in practice but not in the schema. Generated runtime validators (Effect Schema, Zod) then fail on real payloads. Make the schema tell the truth: either drop the nullability or drop the field from required.

2. Unresolvable $refs

References to components that don't exist or live in external files that weren't bundled. Quicktype can't infer a type from a dangling pointer. Bundle the spec into a single file (or fix the reference paths) before feeding it to the generator.

3. Ambiguous union types

Overlapping oneOf/anyOf branches, or unions without a discriminator. Quicktype merges them into overly-loose types or picks the wrong branch. Add a discriminator or tighten the branches so each case is distinguishable.

4. Untyped objects and free-form maps

type: object with no properties or additionalProperties becomes unknown/any in the output — which defeats the point of generating types. Spell out the shape, or declare an explicit map type.

Fix workflow: from broken output to accurate types

  1. 1Run the full spec through the free OpenAPI validator — required/nullable conflicts, dangling $refs, and ambiguous schemas get flagged with line numbers
  2. 2Fix the flagged schemas — the OpenAPI errors cheat sheet shows broken and corrected snippets side by side
  3. 3Re-run Quicktype against the cleaned schemas, e.g. npx quicktype -s schema schemas.json -o types.ts --lang typescript-effect-schema
  4. 4Working from a third-party spec that updates under you? Diff the versions before regenerating so type changes don't surprise you

Using a different tool?

Tell us which generator or importer your spec has to satisfy — the most-requested target gets first-class support next.

Frequently Asked Questions

Garbage in, garbage types out

Validate the source spec first, fix the flagged schemas, and Quicktype's output takes care of itself. Free, no account needed.

Validate My Spec Now