JSON Schema to TypeScript

Appearance

Introduction ​

json-schema-to-typescript compiles JSON Schema to TypeScript typings.

Check out the live demo.

INFO

This library is forked from https://github.com/bcherny/json-schema-to-typescript. Consider to support the original repo by giving it a star.

Installation ​

sh
npm install @fumari/json-schema-to-typescript
sh
pnpm add @fumari/json-schema-to-typescript
sh
yarn add @fumari/json-schema-to-typescript

Usage ​

Transform your JSON Schema to TypeScript Definitions.

js
import { compile } from '@fumari/json-schema-to-typescript'

const mySchema = {
  properties: [...]
}

compile(mySchema, 'MySchema')
  .then(ts => console.log(ts))

YAML and JSON files are also supported.

js
import fs from 'node:fs'
import { compileJsonFile, compileYamlFile } from '@fumari/json-schema-to-typescript'

compileJsonFile(fs.readFileSync('foo.json'), 'MyType').then(ts => fs.writeFileSync('foo.d.ts', ts))

compileYamlFile(fs.readFileSync('foo.yaml'), 'MyType').then(ts => fs.writeFileSync('foo.d.ts', ts))

You can see Options for available options.

Handling $ref ​

You can either:

  • Pass a dereferenced schema, along with a schemaToId option:

    ts
    import { compile } from '@fumari/json-schema-to-typescript'
import { refsPlugin } from '@fumari/json-schema-to-typescript/plugins/refs'

const res = await compile(dereferenced, 'Person', {
  schemaToId: {
    get(schema) {
      // return the original $ref ID of given schema
      return '...'
    }
  }
})

  • Use the refsPlugin() to enable built-in dereferencing:

    ts
    import { compile } from '@fumari/json-schema-to-typescript'
import { refsPlugin } from '@fumari/json-schema-to-typescript/plugins/refs'

const res = await compile(schema, 'Person', {
  plugins: [refsPlugin()]
})

    INFO

    This requires @apidevtools/json-schema-ref-parser to be installed.

Formatting ​

By default, it doesn't format the output TypeScript code.

You can install prettier and enable the Prettier plugin to format output:

sh
npm install prettier
sh
pnpm add prettier
sh
yarn add prettier
js
import { compile } from '@fumari/json-schema-to-typescript'
import { prettierPlugin } from '@fumari/json-schema-to-typescript/plugins/prettier'

const mySchema = {
  properties: [...]
}

await compile(mySchema, 'MySchema', {
  plugins: [prettierPlugin()]
})

Features ​

Supported ​

  • title => interface
  • Primitive types:
    • array
    • homogeneous array
    • boolean
    • integer
    • number
    • null
    • object
    • string
    • homogeneous enum
    • heterogeneous enum
  • Non/extensible interfaces
  • 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
  • minItems
  • additionalProperties of type
  • patternProperties (partial support)
  • extends
  • required properties on objects
  • literal objects in enum
  • referencing schema by id
  • custom typescript types via tsType

Unsupported ​

  • validateRequired
  • Custom JSON-schema extensions

Not expressible in TypeScript ​

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.

ts
export const input = {
  title: 'CustomType',
  type: 'object',
  properties: {
    bar: {
      description: 'Comparator function',
      instanceOf: 'Function',
      tsType: '(a: number, b: number) => number'
    },
    foobar: { $ref: '#/definitions/foobar' }
  },
  definitions: {
    foobar: {
      description: 'Map from number to string',
      tsType: 'Map<number, string>'
    }
  }
}

tsEnumNames ​

Overrides the names used for the elements in an enum. Can also be used to create string enums.

json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "WP_Post_Status_Name",
  "type": "string",
  "tsEnumNames": ["publish", "draft", "auto_draft"],
  "enum": ["publish", "draft", "auto-draft"]
}

FAQ ​

It is crashing on my giant file. What can I do? ​

  1. Disable code formatting if you've Prettier plugin enabled.
  2. Check if there's any issue resolving recursive schemas, welcome to open a bug report.

Further Reading ​