bcherny
json-schema-to-typescript 
Compile JSON Schema to TypeScript typings.
Example
Check out the live demo.
Input:
{
"title": "Example Schema",
"type": "object",
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"age": {
"description": "Age in years",
"type": "integer",
"minimum": 0
},
"hairColor": {
"enum": ["black", "brown", "blue"],
"type": "string"
}
},
"additionalProperties": false,
"required": ["firstName", "lastName"]
}Output:
export interface ExampleSchema {
firstName: string;
lastName: string;
/**
* Age in years
*/
age?: number;
hairColor?: "black" | "brown" | "blue";
}Installation
npm install json-schema-to-typescriptUsage
json-schema-to-typescript is easy to use via the CLI, or programmatically.
CLI
First make the CLI available using one of the following options:
# install locally, then use `npx json2ts`
npm install json-schema-to-typescript
# or install globally, then use `json2ts`
npm install json-schema-to-typescript --global
# or install to npm cache, then use `npx --package=json-schema-to-typescript json2ts`
# (you don't need to run an install command first)Then, use the CLI to convert JSON files to TypeScript typings:
cat foo.json | json2ts > foo.d.ts
# or
json2ts foo.json > foo.d.ts
# or
json2ts foo.yaml foo.d.ts
# or
json2ts --input foo.json --output foo.d.ts
# or
json2ts -i foo.json -o foo.d.ts
# or (quote globs so that your shell doesn't expand them)
json2ts -i 'schemas/**/*.json'
# or
json2ts -i schemas/ -o types/You can pass any of the options described below (including style options) as CLI flags. Boolean values can be set to false using the no- prefix.
# generate code for definitions that aren't referenced
json2ts -i foo.json -o foo.d.ts --unreachableDefinitions
# use single quotes and disable trailing semicolons
json2ts -i foo.json -o foo.d.ts --style.singleQuote --no-style.semiAPI
To invoke json-schema-to-typescript from your TypeScript or JavaScript program, import it and call compile or compileFromFile.
import { compile, compileFromFile } from 'json-schema-to-typescript'
// compile from file
compileFromFile('foo.json')
.then(ts => fs.writeFileSync('foo.d.ts', ts))
// or, compile a JS object
let mySchema = {
properties: [...]
}
compile(mySchema, 'MySchema')
.then(ts => ...)See server demo and browser demo for full examples.
Options
compileFromFile and compile accept options as their last argument (all keys are optional):
| key | type | default | description |
|---|---|---|---|
| additionalProperties | boolean | true |
Default value for additionalProperties, when it is not explicitly set |
| bannerComment | string | "/* eslint-disable */\n/**\n* This file was automatically generated by json-schema-to-typescript.\n* DO NOT MODIFY IT BY HAND. Instead, modify the source JSON Schema file,\n* and run json-schema-to-typescript to regenerate this file.\n*/" |
Disclaimer comment prepended to the top of each generated file |
| customName | (LinkedJSONSchema, string | undefined) => string | undefined |
undefined |
Custom function to provide a type name for a given schema |
| cwd | string | process.cwd() |
Root directory for resolving $refs |
| declareExternallyReferenced | boolean | true |
Declare external schemas referenced via $ref? |
| enableConstEnums | boolean | true |
Prepend enums with const? |
| inferStringEnumKeysFromValues | boolean | false |
Create enums from JSON enums with eponymous keys |
| format | boolean | true |
Format code? Set this to false to improve performance. |
| ignoreMinAndMaxItems | boolean | false |
Ignore maxItems and minItems for array types, preventing tuples being generated. |
| maxItems | number | 20 |
Maximum number of unioned tuples to emit when representing bounded-size array types, before falling back to emitting unbounded arrays. Increase this to improve precision of emitted types, decrease it to improve performance, or set it to -1 to ignore maxItems. |
| strictIndexSignatures | boolean | false |
Append all index signatures with | undefined so that they are strictly typed. |
| style | object | { bracketSpacing: false, printWidth: 120, semi: true, singleQuote: false, tabWidth: 2, trailingComma: 'none', useTabs: false } |
A Prettier configuration |
| unknownAny | boolean | true |
Use unknown instead of any where possible |
| unreachableDefinitions | boolean | false |
Generates code for $defs that aren't referenced by the schema. |
| $refOptions | object | {} |
$RefParser Options, used when resolving $refs |
Tests
$ npm testFeatures
- <input checked="" disabled="" type="checkbox">
title=>interface - <input checked="" disabled="" type="checkbox"> Primitive types:
- <input checked="" disabled="" type="checkbox"> array
- <input checked="" disabled="" type="checkbox"> homogeneous array
- <input checked="" disabled="" type="checkbox"> boolean
- <input checked="" disabled="" type="checkbox"> integer
- <input checked="" disabled="" type="checkbox"> number
- <input checked="" disabled="" type="checkbox"> null
- <input checked="" disabled="" type="checkbox"> object
- <input checked="" disabled="" type="checkbox"> string
- <input checked="" disabled="" type="checkbox"> homogeneous enum
- <input checked="" disabled="" type="checkbox"> heterogeneous enum
- <input checked="" disabled="" type="checkbox"> Non/extensible interfaces
- <input disabled="" type="checkbox"> Custom JSON-schema extensions
- <input checked="" disabled="" type="checkbox"> Nested properties
- <input checked="" disabled="" type="checkbox"> Schema definitions
- <input checked="" disabled="" type="checkbox"> Schema references
- <input checked="" disabled="" type="checkbox"> Local (filesystem) schema references
- <input checked="" disabled="" type="checkbox"> External (network) schema references
- <input checked="" disabled="" type="checkbox"> Add support for running in browser
- <input checked="" disabled="" type="checkbox"> default interface name
- <input checked="" disabled="" type="checkbox"> infer unnamed interface name from filename
- <input checked="" disabled="" type="checkbox">
deprecated - <input checked="" disabled="" type="checkbox">
allOf("intersection") - <input checked="" disabled="" type="checkbox">
anyOf("union") - <input checked="" disabled="" type="checkbox">
oneOf(treated likeanyOf) - <input checked="" disabled="" type="checkbox">
maxItems(eg) - <input checked="" disabled="" type="checkbox">
minItems(eg) - <input checked="" disabled="" type="checkbox">
additionalPropertiesof type - <input checked="" disabled="" type="checkbox">
patternProperties(partial support) - <input checked="" disabled="" type="checkbox">
extends - <input checked="" disabled="" type="checkbox">
requiredproperties on objects (eg) - <input disabled="" type="checkbox">
validateRequired(eg) - <input checked="" disabled="" type="checkbox"> literal objects in enum (eg)
- <input checked="" disabled="" type="checkbox"> referencing schema by id (eg)
- <input checked="" disabled="" type="checkbox"> custom typescript types via
tsType
Custom schema properties:
tsType: Overrides the type that's generated from the schema. Useful for forcing a type toanyor when using non-standard JSON schema extensions (eg).tsEnumNames: Overrides the names used for the elements in an enum. Can also be used to create string enums (eg).
Not expressible in TypeScript:
dependencies(single, multiple)divisibleBy(eg)format(eg)multipleOf(eg)maximum(eg)minimum(eg)maxProperties(eg)minProperties(eg)not/disallowoneOf("xor", useanyOfinstead)pattern(string, regex)uniqueItems(eg)
FAQ
JSON-Schema-to-TypeScript is crashing on my giant file. What can I do?
Prettier is known to run slowly on really big files. To skip formatting and improve performance, set the format option to false.
Further Reading
- JSON-schema spec: https://tools.ietf.org/html/draft-zyp-json-schema-04
- JSON-schema wiki: https://github.com/json-schema/json-schema/wiki
- JSON-schema test suite: https://github.com/json-schema/JSON-Schema-Test-Suite/blob/node
- TypeScript spec: https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md