/json-schema-to-typescript

Compile JSONSchema to TypeScript typings

Primary LanguageTypeScript

json-schema-to-typescript Build Status npm mit

Compile json schema to typescript typings

Example

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

# Using Yarn:
yarn add json-schema-to-typescript

# Or, using NPM:
npm install json-schema-to-typescript --save

Usage

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 note
cwd string Root directory for resolving $refs
declareExternallyReferenced boolean Declare external schemas referenced via $ref?
enableConstEnums boolean Prepend enums with const?
style object A Prettier configuration
unreachableDefinitions boolean Generates code for definitions that aren't referenced by the schema.

CLI

A simple CLI utility is provided with this package.

cat foo.json | json2ts > foo.d.ts
# or
json2ts foo.json > foo.d.ts
# or
json2ts foo.json foo.d.ts
# or
json2ts --input foo.json --output foo.d.ts
# or
json2ts -i foo.json -o foo.d.ts

Tests

npm test

Todo

  • 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
  • allOf ("intersection")
  • anyOf ("union")
  • oneOf (treated like anyOf)
  • additionalProperties of type
  • extends
  • required properties on objects (eg)
  • validateRequired (eg)
  • literal objects in enum (eg)
  • referencing schema by id (eg)

Not expressible in TypeScript:

  • dependencies (single, multiple)
  • divisibleBy (eg)
  • format (eg)
  • multipleOf (eg)
  • maximum (eg)
  • minimum (eg)
  • maxItems (eg)
  • minItems (eg)
  • maxProperties (eg)
  • minProperties (eg)
  • not/disallow
  • oneOf ("xor", use anyOf instead)
  • pattern (string, regex)
  • patternProperties (eg)
  • uniqueItems (eg)

Further Reading