json-schema-to-typescript

Compile JSON Schema to TypeScript typings.

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";
}

npm install json-schema-to-typescript

Requires Node.js 22.19 or later. (json-schema-to-typescript 16.x is the last release line that runs on Node.js 16–20.)

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

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' -o types/
# 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.

The CLI automatically loads the closest Prettier configuration for the generated output file (when writing to stdout: for a .d.ts next to the input file, or in the working directory for piped input). Explicit --style.* flags take precedence over discovered settings, and the output is always parsed as TypeScript whatever parser the config names. A Prettier config that cannot be loaded (invalid syntax, a missing plugin) now fails the run. This does not affect the programmatic API.

# 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
# pass options to the $ref resolver (quote the flag, so that your shell leaves the `$` alone)
json2ts -i foo.json -o foo.d.ts '--$refOptions.dereference.externalReferenceResolution=root'

By default each input file is compiled on its own, so a type that several files reach through a $ref is declared again in every output file. With --imports, a directory or glob is compiled together: a type that lives in another file of the set becomes an import type from that file's module instead of a copy.

json2ts -i schemas/ -o types/ --imports

For example, with common.json holding shared definitions, and a.json and b.json using them and each other:

// schemas/common.json
{
  "title": "Common",
  "type": "object",
  "additionalProperties": false,
  "definitions": {
    "thing": {
      "title": "Thing",
      "type": "object",
      "properties": {"id": {"type": "string"}, "tags": {"type": "array", "items": {"$ref": "#/definitions/tag"}}},
      "required": ["id"],
      "additionalProperties": false
    },
    "tag": {"title": "Tag", "type": "string", "enum": ["red", "green"]}
  }
}
// schemas/a.json
{
  "title": "A",
  "type": "object",
  "properties": {"thing": {"$ref": "common.json#/definitions/thing"}, "partner": {"$ref": "b.json"}},
  "additionalProperties": false
}
// schemas/b.json
{
  "title": "B",
  "type": "object",
  "properties": {"thing": {"$ref": "common.json#/definitions/thing"}, "owner": {"$ref": "a.json"}},
  "additionalProperties": false
}

// types/a.d.ts
import type {B} from "./b.js";
import type {Thing} from "./common.js";

export interface A {
  thing?: Thing;
  partner?: B;
}
// types/b.d.ts
import type {A} from "./a.js";
import type {Thing} from "./common.js";

export interface B {
  thing?: Thing;
  owner?: A;
}
// types/common.d.ts
export type Tag = "red" | "green";

export interface Common {}
export interface Thing {
  id: string;
  tags?: Tag[];
}

(Without --imports, a.d.ts and b.d.ts each declare their own Thing, Tag, A and B, plus a second A1/B1 where the cycle comes back around, and common.d.ts declares only Common.)

What each file gets:

• What a file can import from another is that file's root type, everything under its definitions/$defs, and any other named schema its root type reaches. A $ref to anything else in it (say other.json#/properties/x with no title), to a file outside the set, or to a URL, is declared inline as before; so is a $ref that carries keywords of its own (eg. a description), since it describes a different type. Schemas under other keys, such as OpenAPI's components/schemas, are not importable yet.
• Every file's definitions are declared whether or not the file uses them (unreachableDefinitions is on for the set), so a file's output is what json2ts thatFile.json --unreachableDefinitions prints, minus the declarations that now come from an import, plus the import type lines.
• Each file keeps the type names it would have on its own; where two files disagree, the import renames (import type {Thing as Thing1}). Files that $ref each other in a cycle are fine.
• Import paths are relative, from each output file to the other, and end in .js, which TypeScript resolves to the .d.ts (or .ts) next to it under every moduleResolution setting.
• Relative $refs resolve against the file they appear in; --cwd cannot be combined with --imports, and --imports needs an output directory.

The same is available programmatically as compileFiles, which returns the TypeScript for each file, in order, and writes nothing (the output paths are only used to compute the import paths):

import { compileFiles } from 'json-schema-to-typescript'

const [a, b, common] = await compileFiles(
  [
    {filename: 'schemas/a.json', outputPath: 'types/a.d.ts'},
    {filename: 'schemas/b.json', outputPath: 'types/b.d.ts'},
    {filename: 'schemas/common.json', outputPath: 'types/common.d.ts'},
  ],
  {bannerComment: ''},
)

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.

compileFromFile and compile accept options as their last argument (all keys are optional):

This repo uses bun (1.3.9 or later) to install dependencies and run its scripts and tests, so install it first:

$ bun install
$ bun run test

• 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)
• tuples: array-form items + additionalItems (draft 4 – 2019-09) and prefixItems + items (draft 2020-12)
• additionalProperties of type
• patternProperties (partial support)
• extends
• required properties on objects (eg)
• validateRequired (draft 3 style required: true on a property) (eg)
• literal objects in enum (eg)
• referencing schema by id (eg)
• custom typescript types via tsType
• readOnly → readonly properties and arrays (readonlyKeyword option)

• 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). The names must be distinct strings, one per enum value; otherwise the schema is rejected with a ValidationError. A name TypeScript would read as a number ("1", "-1", "2.5") cannot be an enum member's name, so it gets a leading underscore (_1 = 1); the same goes for a value that inferStringEnumKeysFromValues turns into a name. A TypeScript enum holds strings and numbers only: an enum with a null, boolean, object or array value is typed as a union of its values (null | "a" | "b") instead, and the names go unused.

• dependencies (single, multiple)
• divisibleBy (eg)
• format (eg) — but see the formatTypes option to map a format to a type of your choosing
• multipleOf (eg)
• maximum (eg)
• minimum (eg)
• maxProperties (eg)
• minProperties (eg)
• not/disallow
• oneOf ("xor", use anyOf instead)
• pattern (string, regex)
• uniqueItems (eg)

Every draft goes through the same pipeline; a $schema declaration does not change the output. The schema model is draft 4 (JSONSchema4 from @types/json-schema): the lists above cover its keywords, the table below covers what later drafts added. "Supported" means the keyword shapes the emitted type as the spec intends; keywords that only constrain values have no TypeScript equivalent and are ignored next to a type (a subschema made of nothing else still comes out as {[k: string]: unknown} rather than unknown, #806 pending). As of master d86f285, which is ahead of 16.0.0 (there unevaluatedProperties is still ignored and formatTypes does not exist); every row was checked by compiling a one-keyword schema with the CLI.

Not supported from 2019-09 / 2020-12, by name: $anchor, $recursiveRef, $recursiveAnchor, $dynamicRef, $dynamicAnchor, $vocabulary, unevaluatedItems, prefixItems, dependentSchemas, dependentRequired, minContains, maxContains, contentSchema, and $id-based reference resolution.

Turn formatting off: --no-format on the command line, format: false in the API. Most of the time and much of the memory of compiling a large schema go to Prettier, and the unformatted output is indented, one member per line, and perfectly readable — it just isn't wrapped to a line width. Measured on this repository's benchmark set (node bench/bench.mjs, Node 22):

(wall-clock time of one compile() call and the peak memory of the process.) For anything you generate in a build step rather than commit and read, format: false is the recommended setting.

• JSON Schema specification (2020-12, with links to every earlier draft): https://json-schema.org/specification
• Draft 4, the schema model used here: https://json-schema.org/draft-04/draft-zyp-json-schema-04
• What changed per draft: draft 6, draft 7, 2019-09, 2020-12
• Understanding JSON Schema: https://json-schema.org/understanding-json-schema
• JSON Schema test suite: https://github.com/json-schema-org/JSON-Schema-Test-Suite
• TypeScript handbook: https://www.typescriptlang.org/docs/handbook/

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