typescript-json-schema: the README recommends a different generator

The first paragraph of the README recommends another generator

The opening paragraph is not a pitch. It says the library is lightweight and more or less in maintenance mode, then names ts-json-schema-generator as the more complete option and links to it. That framing is worth reading before anything else in the file, because it tells you what kind of dependency you are adding: something that is still there, still installable, and not where new schema work is going.

What the project does describe is narrow and useful. It compiles your TypeScript program to get complete type information, then translates required properties, extends, annotation keywords and property initializers as defaults into the schema. Two places are offered as the specification of that behaviour: api.md and the test programs under test/programs, which is a stronger promise than prose documentation because those programs are the fixtures the test suite runs against.

The default branch was pushed on 14 July 2026, and the package manifest carries version 0.68.0. The repository publishes no tagged releases, so the npm version is the only version coordinate in play.

The printed usage block stops at --defaultProps and never mentions --include

The command prints its own help, and the block in the documentation ends mid-table:

Usage: typescript-json-schema <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.

Four options carry a type annotation and a default value. The fifth, `--defaultProps`, carries neither, which reads like the list itself is unfinished rather than like the flag being special.

Two options that the prose relies on are absent from the list entirely. `--include` is described in the section above as the way to restrict generation to some types, and `tsNodeRegister` is named later as the argument you must set to true for the require-annotation feature to work. If you read only the help output you will not know either exists.

Two ways in: a project tsconfig.json or a glob with built-in presets

Installation is a global npm install:

npm install typescript-json-schema -g

The command takes a path and a type. The path is either a tsconfig.json:

typescript-json-schema project/directory/tsconfig.json TYPE

or a glob, and the difference matters more than it looks. With a tsconfig.json the generator reads your project's own configuration. Without one you pass .ts files directly and it falls back on built-in compiler presets, which are not your project's settings:

typescript-json-schema "project/directory/**/*.ts" TYPE

The `TYPE` argument is a single fully qualified type or `"*"` for every type in the program, and the `--include` option narrows generation to specific filenames or globs, which the documentation recommends for large projects. So there are two independent filters: `--include` selects which files are considered, and the type argument selects what is emitted, with `"*"` meaning all of it.

Programmatically the same three inputs are separate arguments, compiler options and a base path, handed to `getProgramFromFiles` before any schema is generated.

Type names stop being unique in big projects, so there is a symbol list

The programmatic API exists because the command line does not scale, and its central problem is name collisions. In larger projects type names may not be unique, so uniqueness can be enabled in the settings:

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

// A list of all types of a given name can then be retrieved.
const symbolList = generator.getSymbols("MyType");

// Choose the appropriate type, and continue with the symbol's unique name.
generator.getSchemaForSymbol(symbolList[1].name);

Note the index. The second element of the list is selected by position, and only its `name` field is handed to the schema call, so picking the right overload or the right file's version of a type is the caller's decision.

What comes back is a `SymbolRef`, carrying a short `name`, a `typeName`, a `fullyQualifiedName` and the underlying TypeScript `ts.Symbol`. Calling `getSymbols()` with no argument returns every symbol, and two related calls, `getUserSymbols` and `getMainFileSymbols`, return arrays of plain strings instead, which is the cheap way to ask which names exist before paying for the full records.

Annotations need a TJS prefix because the TypeScript compiler consumes @type

The annotation layer turns JSDoc comments into schema keywords, and it works on the ordinary comment text as well. A property documented like this:

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

produces a draft-07 schema with a description taken from the prose, the minimum applied, and the type narrowed from number to integer. The prose sentence becomes the description with no extra annotation at all, which is the cheapest part of the system to use.

The prefix is the interesting detail. The documentation says `@TJS-type` had to be used instead of plain `@type` because of an issue with the TypeScript compiler, and links the compiler issue. So every type override in your source carries a project-specific prefix to route around a toolchain conflict, and `@items` does the same job for array element schemas, either field by field or as one chunk of raw JSON. That same syntax is accepted for `contains` and `additionalProperties`, so a single annotation shape covers three array and object positions.

The ShapesData example prints the wrong definition name and an unfinished object

The array annotation example is the one to be careful with, because the output shown beside it does not match the input. The input declares an interface called ShapesData with two arrays:

export interface ShapesData {
    /**
     * Specify individual fields in items.
     *
     * @items.type integer
     * @items.minimum 0
     */
    sizes: number[];

    /**
     * Or specify a JSON spec:
     *
     * @items {"type":"string","format":"email"}
     */
    emails: string[];
}

The translated JSON that follows defines the shape under the name `Shape`, not `ShapesData`, and the `emails` property stops partway through its items object, with no closing braces and no sign of where the format constraint landed. The `sizes` half of that same block is complete and does show the intended result, an integer array with a minimum of zero.

So the mechanism is documented correctly by the first property and incorrectly by the second, and the definition name in the printed output does not match the interface it came from. Read the input, not the output, when you write your own annotations. The type alias shortcut is simpler: a type alias named `integer` for `number` maps to the integer type, though the documentation warns it does not work for generic types and array types and mainly applies in simple cases.

ts-node and typescript are runtime dependencies, and @types packages ship with it

The dependency list explains what kind of tool this is. A schema generator that reads type information has to compile TypeScript at run time, so the compiler itself is a runtime dependency, pinned to a patch range rather than a minor one:

"ts-node": "^10.9.2",
"typescript": "~5.9.3",

The tilde matters in practice, since a minor bump of the compiler can change inference and therefore change the schema you get.

Two `@types` packages are dependencies rather than devDependencies, `@types/json-schema` and `@types/node`, so they are installed for consumers as well. The rest are ordinary: glob for file selection, yargs for the command line, path-equal for type name comparison, and safe-stable-stringify so key order in the output does not churn between runs.

The package publishes a main entry and typings pointing into dist, plus a bin entry for the command. Its repository field is an SSH URL rather than an https one, a small thing that breaks tooling which expects to clone over https.

Install from git runs tsc and the docs script, and the tests run the compiled output

The prepare script is the first thing that runs when the package is installed from a checkout, and it does two jobs:

"prepare": "tsc && yarn docs",
"test": "tsc && mocha -t 5000 --require source-map-support/register dist/test",

The test suite therefore compiles first and then runs mocha against `dist/test`, not against the TypeScript sources, with a five second timeout per test and source-map support wired in. A `debug` script is also defined, launching node with an inspector on port 19248 and a break, running through ts-node.

The repository layout matches a small project with one library file and one CLI file at the root, plus bin/, test/ and example/ directories holding invoice and miscellaneous fixtures and a product example. api.md is generated rather than hand written, which is what the docs script and update-docs.js are for. Two style configurations sit side by side, a prettier config and tslint.json, and the lock file is yarn.lock, so development is a yarn workflow even though installation for end users is an npm global install.

Editorial conclusion

Choose this generator if your project already has TypeScript sources and you want schemas derived from the compiled program rather than hand-written, because reading real type information is exactly what it does well, and the annotation layer covers the gaps TypeScript leaves, minimums, integer types, array item schemas, embedded examples. Do not choose it expecting new features: the project describes itself as being in maintenance mode and recommends ts-json-schema-generator, and the branch was last pushed on 14 July 2026. Before adopting it, read its own usage output, because the printed option list is shorter than what the prose describes, and check the annotation examples, since one of them prints the wrong definition name. For a new long-lived schema pipeline, weigh the alternative the README names instead of inheriting this one's doc gaps.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. README
4. YousefED/typescript-json-schema on GitHub