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-typescript

Usage

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

API

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 `$ref`s
declareExternallyReferenced	boolean	`true`	Declare external schemas referenced via `$ref`?
enableConstEnums	boolean	`true`	Prepend enums with `const`?
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 `$ref`s

Tests

$ 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