ts-json-schema-generator

Generate JSON schema from your Typescript sources

JSONTypesSchema
vega/ts-json-schema-generatorts-json-schema-generator

README

ts-json-schema-generator


Test codecov npm version

Extended version of https://github.com/xiag-ag/typescript-to-json-schema.

Inspired by [YousefED/typescript-json-schema](https://github.com/YousefED/typescript-json-schema). Here's the differences list:

-   this implementation avoids the use of typeChecker.getTypeAtLocation() (so probably it keeps correct type aliases)
-   processing AST and formatting JSON schema have been split into two independent steps
-   not exported types, interfaces, enums are not exposed in the definitions section in the JSON schema

Contributors


This project is made possible by a community of contributors. We welcome contributions of any kind (issues, code, documentation, examples, tests,...). Please read our code of conduct.

CLI Usage


  1. ``` sh
  2. npm install --save ts-json-schema-generator
  3. ./node_modules/.bin/ts-json-schema-generator --path 'my/project/**/*.ts' --type 'My.Type.Name'
  4. ```

Note that different platforms (e.g. Windows) may use different path separators so you may have to adjust the command above.

Programmatic Usage


  1. ``` js
  2. // main.js

  4. const tsj = require("ts-json-schema-generator");
  5. const fs = require("fs");

  7. /** @type {import('ts-json-schema-generator/dist/src/Config').Config} */
  8. const config = {
  9.     path: "path/to/source/file",
  10.     tsconfig: "path/to/tsconfig.json",
  11.     type: "*", // Or if you want to generate schema for that one type only
  12. };

  14. const output_path = "path/to/output/file";

  16. const schema = tsj.createGenerator(config).createSchema(config.type);
  17. const schemaString = JSON.stringify(schema, null, 2);
  18. fs.writeFile(output_path, schemaString, (err) => {
  19.     if (err) throw err;
  20. });
  21. ```

Run the schema generator via node main.js.

Custom formatting


Extending the built-in formatting is possible by creating a custom formatter and adding it to the main formatter:

1. First we create a formatter, in this case for formatting function types:

  1. ```ts
  2. // my-function-formatter.ts
  3. import { BaseType, Definition, FunctionType, SubTypeFormatter } from "ts-json-schema-generator";
  4. import ts from "typescript";

  6. export class MyFunctionTypeFormatter implements SubTypeFormatter {
  7.     // You can skip this line if you don't need childTypeFormatter
  8.     public constructor(private childTypeFormatter: TypeFormatter) {}

  10.     public supportsType(type: FunctionType): boolean {
  11.         return type instanceof FunctionType;
  12.     }

  14.     public getDefinition(type: FunctionType): Definition {
  15.         // Return a custom schema for the function property.
  16.         return {
  17.             type: "object",
  18.             properties: {
  19.                 isFunction: {
  20.                     type: "boolean",
  21.                     const: true,
  22.                 },
  23.             },
  24.         };
  25.     }

  27.     // If this type does NOT HAVE children, generally all you need is:
  28.     public getChildren(type: FunctionType): BaseType[] {
  29.         return [];
  30.     }

  32.     // However, if children ARE supported, you'll need something similar to
  33.     // this (see src/TypeFormatter/{Array,Definition,etc}.ts for some examples):
  34.     public getChildren(type: FunctionType): BaseType[] {
  35.         return this.childTypeFormatter.getChildren(type.getType());
  36.     }
  37. }
  38. ```

2. Then we add the formatter as a child to the core formatter using the augmentation callback:

  1. ```ts
  2. import { createProgram, createParser, SchemaGenerator, createFormatter } from "ts-json-schema-generator";
  3. import { MyFunctionTypeFormatter } from "./my-function-formatter.ts";
  4. import fs from "fs";

  6. const config = {
  7.     path: "path/to/source/file",
  8.     tsconfig: "path/to/tsconfig.json",
  9.     type: "*", // Or if you want to generate schema for that one type only
  10. };

  12. // We configure the formatter an add our custom formatter to it.
  13. const formatter = createFormatter(config, (fmt, circularReferenceTypeFormatter) => {
  14.     // If your formatter DOES NOT support children, e.g. getChildren() { return [] }:
  15.     fmt.addTypeFormatter(new MyFunctionTypeFormatter());
  16.     // If your formatter DOES support children, you'll need this reference too:
  17.     fmt.addTypeFormatter(new MyFunctionTypeFormatter(circularReferenceTypeFormatter));
  18. });

  20. const program = createProgram(config);
  21. const parser = createParser(program, config);
  22. const generator = new SchemaGenerator(program, parser, formatter, config);
  23. const schema = generator.createSchema(config.type);

  25. const schemaString = JSON.stringify(schema, null, 2);
  26. fs.writeFile(output_path, schemaString, (err) => {
  27.     if (err) throw err;
  28. });
  29. ```

Custom parsing


Similar to custom formatting, extending the built-in parsing works practically the same way:

1. First we create a parser, in this case for parsing construct types:

  1. ```ts
  2. // my-constructor-parser.ts
  3. import { Context, StringType, ReferenceType, BaseType, SubNodeParser } from "ts-json-schema-generator";
  4. // use typescript exported by TJS to avoid version conflict
  5. import ts from "ts-json-schema-generator";

  7. export class MyConstructorParser implements SubNodeParser {
  8.     supportsNode(node: ts.Node): boolean {
  9.         return node.kind === ts.SyntaxKind.ConstructorType;
  10.     }
  11.     createType(node: ts.Node, context: Context, reference?: ReferenceType): BaseType | undefined {
  12.         return new StringType(); // Treat constructors as strings in this example
  13.     }
  14. }
  15. ```

2. Then we add the parser as a child to the core parser using the augmentation callback:

  1. ```ts
  2. import { createProgram, createParser, SchemaGenerator, createFormatter } from "ts-json-schema-generator";
  3. import { MyConstructorParser } from "./my-constructor-parser.ts";
  4. import fs from "fs";

  6. const config = {
  7.     path: "path/to/source/file",
  8.     tsconfig: "path/to/tsconfig.json",
  9.     type: "*", // Or if you want to generate schema for that one type only
  10. };

  12. const program = createProgram(config);

  14. // We configure the parser an add our custom parser to it.
  15. const parser = createParser(program, config, (prs) => {
  16.     prs.addNodeParser(new MyConstructorParser());
  17. });

  19. const formatter = createFormatter(config);
  20. const generator = new SchemaGenerator(program, parser, formatter, config);
  21. const schema = generator.createSchema(config.type);

  23. const schemaString = JSON.stringify(schema, null, 2);
  24. fs.writeFile(output_path, schemaString, (err) => {
  25.     if (err) throw err;
  26. });
  27. ```

Options


  1. ```
  2. -p, --path 'index.ts'
  3.     The path to the TypeScript source file. If this is not provided, the type will be searched in the project specified in the `.tsconfig`.

  5. -t, --type 'My.Type.Name'
  6.     The type the generated schema will represent. If omitted, the generated schema will contain all
  7.     types found in the files matching path. The same is true if '*' is specified.

  9. -i, --id 'generatedSchemaId'
  10.     The `$id` of the generated schema. If omitted, there will be no `$id`.

  12. -e, --expose <all|none|export>
  13.     all: Create shared $ref definitions for all types.
  14.     none: Do not create shared $ref definitions.
  15.     export (default): Create shared $ref definitions only for exported types (not tagged as `@internal`).

  17. -f, --tsconfig 'my/project/tsconfig.json'
  18.     Use a custom tsconfig file for processing typescript (see https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) instead of the default:
  19.     {
  20.         "compilerOptions": {
  21.             "noEmit": true,
  22.             "emitDecoratorMetadata": true,
  23.             "experimentalDecorators": true,
  24.             "target": "ES5",
  25.             "module": "CommonJS",
  26.             "strictNullChecks": false,
  27.         }
  28.     }

  30. -j, --jsDoc <extended|none|basic>
  31.     none: Do not use JsDoc annotations.
  32.     basic: Read JsDoc annotations to provide schema properties.
  33.     extended (default): Also read @nullable, and @asType annotations.

  35. --unstable
  36.     Do not sort properties.

  38. --strict-tuples
  39.     Do not allow additional items on tuples.

  41. --no-top-ref
  42.     Do not create a top-level $ref definition.

  44. --no-type-check
  45.     Skip type checks for better performance.

  47. --no-ref-encode
  48.     Do not encode references. According to the standard, references must be valid URIs but some tools do not support encoded references.

  50. --validation-keywords
  51.     Provide additional validation keywords to include.

  53. -o, --out
  54.     Specify the output file path. Without this option, the generator logs the response in the console.

  56. --additional-properties <true|false>
  57.     Controls whether or not to allow additional properties for objects that have no index signature.

  59.     true: Additional properties are allowed
  60.     false (default): Additional properties are not allowed

  62. --minify
  63.     Minify generated schema (default: false)
  64. ```

Current state


-   interface types
-   enum types
-   union, tuple, type[] types
-   Date, RegExp, URL types
-   string, boolean, number types
-   "value", 123, true, false, null, undefined literals
-   type aliases
-   generics
-   typeof
-   keyof
-   conditional types

Run locally


yarn --silent run run --path 'test/valid-data/type-mapped-array/*.ts' --type 'MyObject'

Debug


yarn --silent run debug --path 'test/valid-data/type-mapped-array/*.ts' --type 'MyObject'

And connect via the debugger protocol.

AST Explorer is amazing for developers of this tool!

Publish


Publishing is handled by a 2-branch pre-release process, configured inpublish-auto.yml. All changes should be based off the default next branch, and are published automatically.

-   PRs made into the default branch are auto-deployed to the next pre-release tag on NPM. The result can be installed with npm install ts-json-schema-generator@next
    -   When merging into next, please use the squash and merge strategy.
-   To release a new stable version, open a PR from next into stable using this compare link.
    -   When merging from next into stable, please use the create a merge commit strategy.