Home

Awesome

json-schema-to-typescript Build Status npm mit node

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):

keytypedefaultdescription
additionalPropertiesbooleantrueDefault value for additionalProperties, when it is not explicitly set
bannerCommentstring"/* 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 | undefinedundefinedCustom function to provide a type name for a given schema
cwdstringprocess.cwd()Root directory for resolving $refs
declareExternallyReferencedbooleantrueDeclare external schemas referenced via $ref?
enableConstEnumsbooleantruePrepend enums with const?
inferStringEnumKeysFromValuesbooleanfalseCreate enums from JSON enums with eponymous keys
formatbooleantrueFormat code? Set this to false to improve performance.
ignoreMinAndMaxItemsbooleanfalseIgnore maxItems and minItems for array types, preventing tuples being generated.
maxItemsnumber20Maximum 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.
strictIndexSignaturesbooleanfalseAppend all index signatures with | undefined so that they are strictly typed.
styleobject{ bracketSpacing: false, printWidth: 120, semi: true, singleQuote: false, tabWidth: 2, trailingComma: 'none', useTabs: false }A Prettier configuration
unknownAnybooleantrueUse unknown instead of any where possible
unreachableDefinitionsbooleanfalseGenerates code for $defs that aren't referenced by the schema.
$refOptionsobject{}$RefParser Options, used when resolving $refs

Tests

$ npm test

Features

Custom schema properties:

Not expressible in TypeScript:

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

Who uses JSON-Schema-to-TypeScript?