typescript-json-schema

Generate json-schemas from your Typescript sources.

Features

• Compiles your Typescript program to get complete type information.
• Translates required properties, extends, annotation keywords, property initializers as defaults. You can find examples for these features in the test examples.

Usage

Command line

• Install with npm install typescript-json-schema -g
• Generate schema from a typescript type: typescript-json-schema project/directory/tsconfig.json fully.qualified.type.to.generate

In case no tsconfig.json is available for your project, you can directly specify the .ts files (this in this case we use some built-in compiler presets):

• Generate schema from a typescript type: typescript-json-schema "project/directory/**/*.ts" fully.qualified.type.to.generate

Usage: node typescript-json-schema.js <path-to-typescript-files-or-tsconfig> <type>
Options:
--refs Create shared ref definitions. [boolean] [default: true]
--aliasRefs Create shared ref definitions for the type aliases. [boolean] [default: false]
--topRef Create a top-level ref definition. [boolean] [default: false]
--titles Creates titles in the output schema. [boolean] [default: false]
--defaultProps Create default properties definitions. [boolean] [default: false]
--noExtraProps Disable additional properties in objects by default. [boolean] [default: false]
--propOrder Create property order definitions. [boolean] [default: false]
--required Create required array for non-optional properties. [boolean] [default: false]
--strictNullChecks Make values non-nullable by default. [boolean] [default: false]
--useTypeOfKeyword Use `typeOf` keyword (https://goo.gl/DC6sni) for functions. [boolean] [default: false]
--out, -o The output file, defaults to using stdout
--validationKeywords Provide additional validation keywords to include [array] [default: []]

Programmatic use

import{resolve}from"path";import{CompilerOptions}from"typescript";import*asTJSfrom"typescript-json-schema";// optionally pass argument to schema generatorconstsettings: TJS.PartialArgs={generateRequired: true};// optionally pass ts compiler options
compilerOptions: CompilerOptions={strictNullChecks: true}constprogram=TJS.getProgramFromFiles([resolve("my-file.ts")],compilerOptions);// We can either get the schema for one file and one type...constschema=TJS.generateSchema(program,"MyType",settings);// ... or a generator that lets us incrementally get more schemasconstgenerator=TJS.buildGenerator(program,settings);// all symbolsconstsymbols=generator.getUserSymbols();// Get symbols for different types from generator.generator.getSchemaForSymbol("MyType");generator.getSchemaForSymbol("AnotherType");

Annotations

The schema generator converts annotations to JSON schema properties.

For example

exportinterfaceShape{/** * The size of the shape. * * @minimum 0 * @TJS-type integer */size: number;}

will be translated to

{
"$ref": "#/definitions/Shape",
"$schema": "http://json-schema.org/draft-04/schema#",
"definitions": {
"Shape": {
"properties": {
"size": {
"description": "The size of the shape.",
"minimum": 0,
"type": "integer"
}
},
"type": "object"
}
}
}

Note that we needed to use @TJS-type instead of just @type because of an issue with the typescript compiler.

Background

Inspired and builds upon Typson, but typescript-json-schema is compatible with more recent Typescript versions. Also, since it uses the Typescript compiler internally, more advanced scenarios are possible.

Debugging

npm run debug -- test/programs/type-alias-single/main.ts --aliasRefs true MyString

And connect via the debugger protocol.