To help you get started, we've collected the most common ways that json-schema-to-typescript is being used within popular public projects.

interledgerjs / rafiki / scripts / build_schema_types.js View on Github

;(async function () {
  for (let schema of schemas) {
    // Have to pass an empty options object, otherwise we trigger a bug where
    // the cwd for the JSON schema $ref resolver defaults to the current
    // working directory instead of the file's directory.
    let ts = await compileFromFile(resolve(__dirname, '../src/schemas/', schema), {})

    if (schema === 'Config.json') {
      ts = ts
        // This is the only way to let Config inherit from the interface without
        // redefining all the fields.
        .replace('export interface Config', 'export class Config')
        // Ignore the error stating that `accounts` isn't assigned in the
        // constructor.
        .replace('accounts: {', 'accounts!: {')
    }

    fs.writeFileSync(resolve(__dirname, '../src/schemas/', schema.split('.')[0] + 'Typing.ts'), ts)
  }
})()
  .catch(err => console.error(err))

View more ways to use json-schema-to-typescript

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

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

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

• JSON-schema spec: https://tools.ietf.org/html/draft-zyp-json-schema-04
• JSON-schema wiki: https://github.com/json-schema/json-schema/wiki
• JSON-schema test suite: https://github.com/json-schema/JSON-Schema-Test-Suite/blob/node
• TypeScript spec: https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md

Who uses JSON-Schema-to-TypeScript?

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