Package Exports

json-schema-to-typescript
json-schema-to-typescript/dist/src/formatter
json-schema-to-typescript/dist/src/formatter.js
json-schema-to-typescript/dist/src/generator
json-schema-to-typescript/dist/src/generator.js
json-schema-to-typescript/dist/src/index.js
json-schema-to-typescript/dist/src/normalizer
json-schema-to-typescript/dist/src/normalizer.js
json-schema-to-typescript/dist/src/optimizer
json-schema-to-typescript/dist/src/optimizer.js
json-schema-to-typescript/dist/src/parser
json-schema-to-typescript/dist/src/parser.js
json-schema-to-typescript/dist/src/resolver
json-schema-to-typescript/dist/src/resolver.js
json-schema-to-typescript/dist/src/types/AST
json-schema-to-typescript/dist/src/types/AST.js
json-schema-to-typescript/dist/src/utils
json-schema-to-typescript/dist/src/utils.js
json-schema-to-typescript/dist/src/validator
json-schema-to-typescript/dist/src/validator.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (json-schema-to-typescript) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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`?
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 `$ref`s

Tests

$ npm test

Features

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