typescript-json-schema: generating JSON Schema from TypeScript types

The gap typescript-json-schema fills between TypeScript types and JSON Schema

A TypeScript interface is a compile-time construct. It disappears from the emitted JavaScript, so anything that consumes data at runtime (a form renderer, an API gateway, a config validator) cannot see it. JSON Schema is the runtime counterpart: a document that describes the shape, required fields and constraints of a JSON value, and that validators such as Ajv can execute.

Keeping the two in sync by hand is the problem this project addresses. You write the interface once, run the generator, and get a schema derived from the same declaration the compiler already checks. The audience is TypeScript teams that own the types and need a schema artifact for something downstream, rather than teams that start from a schema and want types generated from it.

The README is unusually direct about the project's position: it calls the library "lightweight and more or less in maintenance mode" and points readers to ts-json-schema-generator for "a more complete JSON schema generator". Treat that as the honest framing of what you are adopting. This is a focused tool that does one translation, not a framework.

How the generator reads your program and emits a draft-07 schema

The mechanism is not a regex over source files. According to the README, the tool "compiles your Typescript program to get complete type information", which means it drives the TypeScript compiler API and reads resolved symbols rather than parsing text. That distinction matters for generics, imported types and anything that requires the checker to resolve.

You point it at either a tsconfig.json or a set of .ts files. With a tsconfig it uses your compiler settings; without one, the README says the tool falls back to "some built-in compiler presets". The second argument is the type name, either a fully qualified type or "*" for every type in the program. Output goes to stdout unless you pass --out.

The emitted document is draft-07, visible in the annotation example where the output carries "$schema": "http://json-schema.org/draft-07/schema#". Several behaviours are off by default and have to be requested: --required builds the required array for non-optional properties, --noExtraProps disables additional properties, --titles adds titles, and --defaultProps turns property initializers into defaults. That default-off posture is a real design choice. A generated schema with no required array will accept an object missing every field, which surprises people who expect required to be inferred.

Annotations are the other half of the mechanism. JSDoc tags on a property are translated into schema keywords, so @minimum 0 and @TJS-type integer on a number field become "minimum": 0 and "type": "integer" in the output, and the doc comment text becomes the description. The @TJS- prefix exists because plain JSDoc tags can collide with the TypeScript compiler's own handling.

Installing typescript-json-schema and generating your first schema

The README gives a global install and a single command. The binary is exposed as typescript-json-schema through the package's bin entry, so after a global install the command is on your PATH.

npm install typescript-json-schema -g

The first argument is the path to your tsconfig.json and the second is the type name. Here the type is MyType, and the schema is printed to stdout because no --out flag is given.

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

If your project has no tsconfig.json, the README allows a glob of source files instead, in which case the tool uses its built-in compiler presets.

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

The README notes that --include accepts filenames or globs to limit which files the tsconfig contributes, which it recommends for large projects. In code, the same work is done through getProgramFromFiles and generateSchema, or through buildGenerator when you need schemas for several symbols from one compiled program.

Where typescript-json-schema stops being the right tool

The most concrete limitation is stated by the project itself: maintenance mode. The last push to the repository was on 2026-07-14, and the README recommends ts-json-schema-generator when you want a more complete generator. If your types lean on TypeScript features that have landed recently, verify that the pinned compiler (typescript ~5.9.3 in package.json) resolves the same way your application build does. A generator bound to its own TypeScript dependency can disagree with the compiler your app actually uses.

The second limitation is the default-off flag set. Nothing in the README suggests that required, additionalProperties or titles are inferred; you opt in per invocation. Someone who runs the bare command, commits the output and wires it into a validator has produced a schema that is far more permissive than the interface it came from. That is a silent failure mode, not a loud one.

The third is scope. This is a one-directional tool: TypeScript in, JSON Schema out. If your source of truth is a schema document and you want TypeScript interfaces from it, this project does not do that. And if you need a schema for a runtime value rather than a declared type, there is nothing here to compile.

typescript-json-schema compared with ts-json-schema-generator

The README names the alternative directly, so the comparison is not guesswork: ts-json-schema-generator is described as "a more complete JSON schema generator" and is the project's own recommendation for that need. The difference in approach is the trade the two make. typescript-json-schema is the smaller surface: a global CLI, a handful of boolean flags, a programmatic API built around getProgramFromFiles, generateSchema and buildGenerator. Its feature list is short and its README says so.

A more complete generator typically takes on more of the type system and more configuration, which is exactly what you want when the small tool's coverage runs out, and exactly what you do not want when a single command with predictable output is the goal. There is no benchmark comparing the two, so the honest framing is coverage and maintenance posture rather than speed.

The related searches around this project also surface Json-schema-to-typescript, which runs in the opposite direction: schema as input, TypeScript as output. That is not a competitor to this tool so much as the reverse pipeline, and it is worth knowing which direction your project actually needs before picking either.

Licence, dependencies and what an upgrade costs

The package is BSD-3-Clause, a permissive licence that allows use in closed-source products provided the copyright notice and licence text are retained. That is the general shape of the licence; whether your distribution satisfies it is a question for your own legal review, not something this article can settle.

The dependency list is short and mostly familiar: typescript, ts-node, yargs, glob, safe-stable-stringify, path-equal, plus @types packages. Two of those deserve attention before an upgrade. typescript is pinned with a tilde to ~5.9.3, so a major TypeScript bump in your application does not automatically move the generator, and the generator's output is a function of the compiler it drives. ts-node is a runtime dependency, present because --tsNodeRegister exists for requiring TypeScript files, which also means the dependency tree is heavier than the feature list suggests.

Upgrade cost is mostly re-verification rather than migration. There are no retrieved releases to reason about, and the CLI flags in the README are stable-looking booleans, so the practical work after bumping the version is regenerating your schemas and diffing them. A change in the pinned TypeScript version can alter resolved types and therefore the emitted document without any flag changing.

Editorial conclusion

Adopt typescript-json-schema when your schemas must stay tied to an existing TypeScript codebase and you want one command, or one generateSchema call, to produce them. Skip it when you need a generator that keeps pace with newer TypeScript features or emits richer output; the README points to ts-json-schema-generator for that. Before committing, run the CLI against your own tsconfig.json with --required and check the emitted draft-07 document, and confirm which TypeScript version your project resolves against, since the package pins typescript to ~5.9.3.

Frequently asked questions

Official sources

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