typescript-json-schema

What is typescript-json-schema?

The typescript-json-schema npm package is a tool that generates JSON schemas from your TypeScript types. This can be particularly useful for validating JSON data, generating documentation, or ensuring consistency between your TypeScript code and JSON data structures.

What are typescript-json-schema's main functionalities?

Generate JSON Schema from TypeScript Interface

This feature allows you to generate a JSON schema from a TypeScript interface. The code sample demonstrates how to set up the schema generator, specify the TypeScript file, and generate the schema for a specific interface.

const TJS = require('typescript-json-schema');

// Settings for the schema generator
const settings = {
  required: true
};

// Path to the TypeScript file
const files = ["./example.ts"];

// Generate the schema
const program = TJS.getProgramFromFiles(files);
const schema = TJS.generateSchema(program, "MyInterface", settings);

console.log(JSON.stringify(schema, null, 2));

Generate JSON Schema with Custom Settings

This feature allows you to customize the settings for the JSON schema generation. The code sample demonstrates how to use custom settings such as `noExtraProps` and `propOrder` to control the schema generation process.

const TJS = require('typescript-json-schema');

// Custom settings for the schema generator
const settings = {
  required: true,
  noExtraProps: true,
  propOrder: true
};

// Path to the TypeScript file
const files = ["./example.ts"];

// Generate the schema
const program = TJS.getProgramFromFiles(files);
const schema = TJS.generateSchema(program, "MyInterface", settings);

console.log(JSON.stringify(schema, null, 2));

Generate JSON Schema for Multiple Interfaces

This feature allows you to generate JSON schemas for multiple TypeScript interfaces at once. The code sample demonstrates how to specify multiple interfaces and generate their schemas in a single operation.

const TJS = require('typescript-json-schema');

// Settings for the schema generator
const settings = {
  required: true
};

// Path to the TypeScript file
const files = ["./example.ts"];

// Generate the schema
const program = TJS.getProgramFromFiles(files);
const schema = TJS.generateSchema(program, ["MyInterface1", "MyInterface2"], settings);

console.log(JSON.stringify(schema, null, 2));

Other packages similar to typescript-json-schema

typescript-to-json-schema

The typescript-to-json-schema package is another tool for generating JSON schemas from TypeScript types. It offers similar functionality to typescript-json-schema but with a different API and potentially different performance characteristics.

ts-json-schema-generator

The ts-json-schema-generator package is designed to generate JSON schemas from TypeScript types with a focus on simplicity and ease of use. It provides a straightforward API and is often used for quick schema generation tasks.

json-schema-to-typescript

The json-schema-to-typescript package works in the opposite direction, generating TypeScript types from JSON schemas. This can be useful for ensuring that your TypeScript code matches a given JSON schema, providing a complementary tool to typescript-json-schema.

README

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]
  --out, -o           The output file, defaults to using stdout

Programmatic use

import {resolve} from "path";

import {CompilerOptions} from "typescript";
import * as TJS from "typescript-json-schema";

// optionally pass argument to schema generator
const settings: TJS.PartialArgs = {
    generateRequired: true
};

// optionally pass ts compiler options
compilerOptions: CompilerOptions = {
    strictNullChecks: true
}

const program = TJS.getProgramFromFiles([resolve("my-file.ts")], compilerOptions);

// We can either get the schema for one file and one type...
const schema = TJS.generateSchema(program, "MyType", settings);


// ... or a generator that lets us incrementally get more schemas

const generator = TJS.buildGenerator(program, settings);

// all symbols
const symbols = 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

export interface Shape {
    /**
     * 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.