quicktype generates strongly-typed models and serializers from JSON, JSON Schema, TypeScript, and GraphQL queries, making it a breeze to work with JSON type-safely in many programming languages.
| TypeScript |
GraphQL queries |
Target Languages
Missing your favorite language? Please implement it!
Installation
There are many ways to use quicktype. app.quicktype.io is the most powerful and complete UI. The web app also works offline and doesn't send your sample data over the Internet, so paste away!
The quicktype CLI and Node.js packages require Node.js 20 or newer. See
Migrating to quicktype 24 for upgrade details.
For the best CLI, we recommend installing quicktype globally via npm:
npm install -g quicktype
Using quicktype
# Run quicktype without arguments for help and options
quicktype
# quicktype a simple JSON object in C#
echo '{ "name": "David" }' | quicktype -l csharp
# quicktype a top-level array and save as Go source
echo '[1, 2, 3]' | quicktype -o ints.go
# quicktype a sample JSON file in Swift
quicktype person.json -o Person.swift
# A verbose way to do the same thing
quicktype \
--src person.json \
--src-lang json \
--lang swift \
--top-level Person \
--out Person.swift
# quicktype a directory of samples as a C++ program
# Suppose ./blockchain is a directory with files:
# latest-block.json transactions.json marketcap.json
quicktype ./blockchain -o blockchain-api.cpp
# quicktype a live JSON API as a Java program
quicktype https://api.somewhere.com/data -o Data.java
Generating code from JSON schema
The recommended way to use quicktype is to generate a JSON schema from sample data, review and edit the schema, commit the schema to your project repo, then generate code from the schema as part of your build process:
# First, infer a JSON schema from a sample.
quicktype pokedex.json -l schema -o schema.json
# Review the schema, make changes,
# and commit it to your project repo.
# Finally, generate model code from schema in your
# build process for whatever languages you need:
quicktype -s schema schema.json -o src/ios/models.swift
quicktype -s schema schema.json -o src/android/Models.java
quicktype -s schema schema.json -o src/nodejs/Models.ts
# All of these models will serialize to and from the same
# JSON, so different programs in your stack can communicate
# seamlessly.
Generating code from TypeScript (Experimental)
You can achieve a similar result by writing or generating a TypeScript file, then quicktyping it. TypeScript is a typed superset of JavaScript with simple, succinct syntax for defining types:
interface Person {
name: string;
nickname?: string; // an optional property
luckyNumber: number;
}
You can use TypeScript just like JSON schema was used in the last example:
# First, infer a TypeScript file from a sample (or just write one!)
quicktype pokedex.json -o pokedex.ts --just-types
# Review the TypeScript, make changes, etc.
quicktype pokedex.ts -o src/ios/models.swift
Calling quicktype from JavaScript
You can use quicktype as a JavaScript function within node or browsers. First add the quicktype-core package:
$ npm install quicktype-core
In general, first you create an InputData value with one or more JSON samples, JSON schemas, TypeScript sources, or other supported input types. Then you call quicktype, passing that InputData value and any options you want.
import {
quicktype,
InputData,
jsonInputForTargetLanguage,
JSONSchemaInput,
FetchingJSONSchemaStore
} from "quicktype-core";
async function quicktypeJSON(targetLanguage, typeName, jsonString) {
const jsonInput = jsonInputForTargetLanguage(targetLanguage);
// We could add multiple samples for the same desired
// type, or many sources for other types. Here we're
// just making one type from one piece of sample JSON.
await jsonInput.addSource({
name: typeName,
samples: [jsonString]
});
const inputData = new InputData();
inputData.addInput(jsonInput);
return await quicktype({
inputData,
lang: targetLanguage
});
}
async function quicktypeJSONSchema(targetLanguage, typeName, jsonSchemaString) {
const schemaInput = new JSONSchemaInput(new FetchingJSONSchemaStore());
// We could add multiple schemas for multiple types,
// but here we're just making one type from JSON schema.
await schemaInput.addSource({ name: typeName, schema: jsonSchemaString });
const inputData = new InputData();
inputData.addInput(schemaInput);
return await quicktype({
inputData,
lang: targetLanguage
});
}
async function main() {
const { lines: swiftPerson } = await quicktypeJSON("swift", "Person", jsonString);
console.log(swiftPerson.join("\n"));
const { lines: pythonPerson } = await quicktypeJSONSchema("python", "Person", jsonSchemaString);
console.log(pythonPerson.join("\n"));
}
main();
The argument to quicktype is a complex object with many optional properties. Explore its definition to understand what options are allowed.
TypeScript: the lang option is a LanguageName, not a string
In TypeScript, the lang option of quicktype and the argument of jsonInputForTargetLanguage are typed as LanguageName, a union of all supported language names — passing a plain string is a compile-time error. If the language name is known statically, just pass the literal (lang: "swift"). For wrappers that take the language name at runtime — from CLI arguments or configuration — validate it with the isLanguageName type guard instead of casting:
import { type LanguageName, isLanguageName, quicktype } from "quicktype-core";
async function quicktypeJSON(targetLanguage: LanguageName, typeName: string, jsonString: string) {
// same body as above
}
const lang = process.argv[2]; // untrusted string
if (!isLanguageName(lang)) {
throw new Error(`Unknown language: ${lang}`);
}
// lang now has type LanguageName
const { lines } = await quicktypeJSON(lang, "Person", jsonString);
Bundling quicktype-core as ESM
quicktype-core ships both CommonJS and ESM builds. If you bundle it into an ESM output for Node with esbuild (--format=esm --platform=node), the bundle may throw at runtime:
Error: Dynamic require of "process" is not supported
This is not specific to quicktype: some of its dependencies (e.g. yaml) expose an ESM entry that wraps a CommonJS core, and esbuild replaces require calls inside inlined CommonJS with a shim that throws in ESM output. The standard workaround is to inject a createRequire banner:
esbuild main.js --bundle --format=esm --platform=node \
--banner:js="import { createRequire } from 'module'; const require = createRequire(import.meta.url);"
Bundling to CommonJS output (--format=cjs) works without any workaround.
Adding Custom logic or Rendering:
Quicktype supports creating your own custom languages and rendering output, you can extend existing classes or create your own to be using by the quicktype function.
Check out this guide for more info.
Contributing
quicktype is Open Source and we love contributors! In fact, we have a list of issues that are low-priority for us, but for which we'd happily accept contributions. Support for new target languages is also strongly desired. If you'd like to contribute, need help with anything at all, or would just like to talk things over, come join us on Slack.
Setup, Build, Run
quicktype is implemented in TypeScript and requires nodejs and npm to build and run.
First, install typescript globally via npm:
Clone this repo and do:
macOS / Linux
nvm use
npm install
script/quicktype # rebuild (slow) and run (fast)
Windows
npm install --ignore-scripts # Install dependencies
npm install -g typescript # Install typescript globally
tsc --project src/cli # Rebuild
node dist\cli\index.js # Run
Edit
Install Visual Studio Code, open this
workspace, and install the recommended extensions:
code . # opens in VS Code
Live-reloading for quick feedback
When working on an output language, you'll want to view generated
output as you edit. Use npm start to watch for changes and
recompile and rerun quicktype for live feedback. For example, if you're
developing a new renderer for fortran, you could use the following command to
rebuild and reinvoke quicktype as you implement your renderer:
npm start -- "--lang fortran pokedex.json"
The command in quotes is passed to quicktype, so you can render local .json
files, URLs, or add other options.
Test
# Run full test suite (unit tests plus all fixtures)
npm test
# Run only the Vitest unit tests
npm run test:unit
# Test a specific language (see test/languages.ts)
FIXTURE=golang npm run test:fixtures
# Test a single sample or directory
FIXTURE=swift npm run test:fixtures -- pokedex.json
FIXTURE=swift npm run test:fixtures -- test/inputs/json/samples
quicktype 可以根据 JSON、JSON Schema、TypeScript 和 GraphQL 查询生成强类型的模型和序列化代码，让你能在多种编程语言中安全地处理 JSON。