json-schema-to-typescript [![Build Status][build]](https://github.com/bcherny/json-schema-to-typescript/actions?query=branch%3Amaster+workflow%3ACI) [![npm]](https://www.npmjs.com/package/json-schema-to-typescript) [![mit]](https://opensource.org/licenses/MIT) ![node]

[build]: https://img.shields.io/github/actions/workflow/status/bcherny/json-schema-to-typescript/ci.yml?style=flat-square
[npm]: https://img.shields.io/npm/v/json-schema-to-typescript.svg?style=flat-square
[mit]: https://img.shields.io/npm/l/json-schema-to-typescript.svg?style=flat-square
[node]: https://img.shields.io/badge/Node.js-16+-417e37?style=flat-square

> Compile JSON Schema to TypeScript typings.

Example

Check out the live demo.

Input:

``json
{
"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:

`ts
export interface ExampleSchema {
firstName: string;
lastName: string;
/**
* Age in years
*/
age?: number;
hairColor?: "black" | "brown" | "blue";
}
`

Installation

`sh
npm install json-schema-to-typescript
`

Usage

json-schema-to-typescript is easy to use via the CLI, or programmatically.

$3

First make the CLI available using one of the following options:

`sh


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:

`sh
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.

`sh


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.semi
`

$3

To invoke json-schema-to-typescript from your TypeScript or JavaScript program, import it and call compile or compileFromFile.

`js
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

`sh
$ npm test
`

Features

- [x] title => interface
- [x] Primitive types:
- [x] array
- [x] homogeneous array
- [x] boolean
- [x] integer
- [x] number
- [x] null
- [x] object
- [x] string
- [x] homogeneous enum
- [x] heterogeneous enum
- [x] Non/extensible interfaces
- [ ] Custom JSON-schema extensions
- [x] Nested properties
- [x] Schema definitions
- [x] Schema references
- [x] Local (filesystem) schema references
- [x] External (network) schema references
- [x] Add support for running in browser
- [x] default interface name
- [x] infer unnamed interface name from filename
- [x] deprecated
- [x] allOf ("intersection")
- [x] anyOf ("union")
- [x] oneOf (treated like anyOf)
- [x] maxItems (eg)
- [x] minItems (eg)
- [x] additionalProperties of type
- [x] patternProperties (partial support)
- [x] extends
- [x] required properties on objects (eg)
- [ ] validateRequired (eg)
- [x] literal objects in enum (eg)
- [x] referencing schema by id (eg)
- [x] custom typescript types via tsType

Custom schema properties:

- tsType: Overrides the type that's generated from the schema. Useful for forcing a type to any or 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/disallow
- oneOf ("xor", use anyOf instead)
- pattern (string, regex)
- uniqueItems (eg)

FAQ

$3

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

Who uses JSON-Schema-to-TypeScript?

- Alibaba
- Amazon, AWSLabs
- Expo
- FormatJS
- Microsoft
- Mozilla
- Nx
- RStudio
- Sourcegraph
- Stryker
- Webpack
- See more