# quicktype

> A complete guide to using quicktype to understand data shapes and generate typesafe code. Start here if you already know you want quicktype; use https://quicktype.io/llms.txt for the curated index.

quicktype infers types from sample data and writes models plus serializers in the language you need. It is not a JSON pretty-printer and not a generic "explain this blob" helper. It builds a unified type graph from one or more inputs, then renders idiomatic types.

The more JSON you feed an LLM, the more confused the LLM becomes. The more JSON you give to quicktype, the better quicktype understands it. When an agent needs to understand an API response, a fixture, a webhook, or a schema, run quicktype instead of stuffing raw JSON into context.

## Why agents should use it

- **Shape, not tokens.** quicktype returns named types, optionals, unions, enums, maps, and dates. That is the representation humans and compilers actually use.
- **Many samples help.** Extra examples refine the type. Extra examples in an LLM prompt mostly add noise.
- **One inference, many languages.** Infer a schema once, then emit TypeScript, Swift, C#, Go, Python, Kotlin, Java, Rust, and others that agree on the wire format.
- **Local by default.** The web app works offline and does not upload samples. The CLI and `quicktype-core` run on your machine.

Use quicktype when the task is "what is this data?" or "give me types/serializers for this data." Do not use it when the user only wants a one-off field lookup from a tiny object you can already see.

## Inputs and outputs

Supported inputs: JSON samples (files, directories, URLs, stdin), JSON Schema, TypeScript types, GraphQL queries, and Postman collections.

Supported outputs include TypeScript, Flow, JavaScript, Zod, Effect Schema, Swift, Objective-C, C#, Go, Java, Kotlin, Python, Rust, C++, Dart, Ruby, PHP, Scala, Haskell, Elm, Elixir, Crystal, Pike, JSON Schema, Smithy, C, and others. Open https://app.quicktype.io/ for the current list.

## How to run it

### MCP (preferred for agents)

https://mcp.quicktype.io/ exposes quicktype as an MCP server. Add that URL to the MCP client so the agent can infer types without pasting large JSON into the chat. Use this whenever the client supports MCP.

### CLI

Requires Node.js 20.19 or newer.

```bash
npm install -g quicktype
# or, with no global install:
npx quicktype --help
```

```bash
# stdin
echo '{ "name": "David" }' | quicktype -l csharp

# file, language inferred from -o
quicktype person.json -o Person.swift

# explicit flags
quicktype --src person.json --src-lang json --lang swift --top-level Person --out Person.swift

# live API
quicktype https://api.example.com/data -o Data.java

# directory of samples (best inference)
quicktype ./samples -o Api.ts

# only types, no serializers
quicktype data.json --just-types -o Types.ts

# JSON Schema in, code out
quicktype --src-lang schema schema.json -o Models.py

# JSON in, schema out (commit this)
quicktype data.json -l schema -o schema.json
```

Useful flags: `--lang` / `-l`, `--out` / `-o`, `--top-level`, `--just-types`, `--src-lang` (`json`, `schema`, `typescript`, `graphql`, `postman`). Run `quicktype --help` for language-specific options.

### Web app

https://app.quicktype.io/ — paste JSON, add more samples, pick a language, copy code. Query params: `l` for language (`?l=ts`, `?l=swift`), `s` for built-in samples.

### Library (`quicktype-core`)

```bash
npm install quicktype-core
```

```typescript
import {
  quicktype,
  InputData,
  jsonInputForTargetLanguage,
  isLanguageName,
  type LanguageName,
} from "quicktype-core";

async function quicktypeJSON(lang: LanguageName, typeName: string, json: string) {
  const jsonInput = jsonInputForTargetLanguage(lang);
  await jsonInput.addSource({ name: typeName, samples: [json] });
  const inputData = new InputData();
  inputData.addInput(jsonInput);
  return quicktype({ inputData, lang });
}

const lang = process.argv[2];
if (!isLanguageName(lang)) throw new Error(`Unknown language: ${lang}`);
const { lines } = await quicktypeJSON(lang, "Person", `{"name":"Ada"}`);
console.log(lines.join("\n"));
```

`lang` is a `LanguageName` union, not `string`. Narrow runtime values with `isLanguageName` instead of casting. Deep imports must use `quicktype-core/dist/*`.

## Best-practice workflow

1. Collect real samples. Include edge cases: missing fields, nulls, empty arrays, extra enum values, nested objects that sometimes appear as maps.
2. Infer JSON Schema: `quicktype samples/ -l schema -o schema.json`.
3. Read the schema. Fix names, required fields, and formats. Commit it.
4. Generate code from the schema in each language as part of the build.
5. When the API changes, add samples, update the schema, regenerate.

TypeScript can play the same role as schema: infer or write `.ts` types, then `quicktype types.ts -o Models.swift`.

Multiple samples are not optional for production APIs. A single happy-path payload will mark nullable fields as required, hide unions, and miss map vs class decisions.

## Inference tips

- **Enums.** Repeated string literals become enums when the set looks closed.
- **Dates.** ISO-looking strings can become date types. Confirm formats if the output surprises you.
- **Maps vs classes.** Objects with arbitrary keys become maps; fixed keys become classes. More samples improve this.
- **Unions.** Heterogeneous arrays and properties become unions instead of collapsing to `any`.
- **Names.** Nested types are named from property names; equivalent shapes are unified so you do not get `Foo` and `Foo1` for the same structure.

If generated types look too wide (`string` everywhere) you need better samples or a schema. If they look too narrow (missing optionals), you need more samples, not a larger prompt.

## Language landing pages on this site

- https://quicktype.io/typescript
- https://quicktype.io/swift
- https://quicktype.io/csharp
- https://quicktype.io/objective-c
- https://quicktype.io/postman
- Other languages: https://quicktype.io/{language} where `{language}` is the canonical quicktype name (for example `python`, `go`, `java`, `kotlin`, `rust`).

## Further reading

- Curated index: https://quicktype.io/llms.txt
- Homepage: https://quicktype.io/
- Blog: https://quicktype.io/blog/
- CLI how-to: https://quicktype.io/blog/quicktype-cli
- Multiple samples: https://quicktype.io/blog/quicktype-multiple-samples
- Customizing output: https://quicktype.io/blog/customizing-quicktype
- GraphQL: https://quicktype.io/blog/graphql
- First look: https://quicktype.io/blog/first-look
- GitHub README: https://github.com/glideapps/quicktype
- FAQ: https://github.com/glideapps/quicktype/blob/master/FAQ.md
- npm CLI: https://www.npmjs.com/package/quicktype
- npm core: https://www.npmjs.com/package/quicktype-core