Registry / serialization / typescript-json-schema

typescript-json-schema

JSON →
library0.67.1jsnpmunverified

typescript-json-schema is a library designed to generate JSON Schema definitions directly from TypeScript source files. It operates by compiling the TypeScript program to extract comprehensive type information and then translating this into JSON Schema, including features like required properties, inheritance (`extends`), JSDoc annotation keywords, and default values from property initializers. The current stable version is 0.67.1. The project is explicitly stated to be in "maintenance mode", indicating a slower release cadence and less active feature development compared to its past. While lightweight, the maintainers suggest `ts-json-schema-generator` for a more feature-rich and actively developed alternative, highlighting `typescript-json-schema`'s primary differentiator as its use of the TypeScript compiler internally, enabling advanced scenarios.

npm install typescript-json-schema
INSTALL
IMPORT
SIG · TYPESCRIPT-JSON-SC
T
typescript-json-schema
serializationjavascriptv0.67.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

buildGenerator
import * as TJS from 'typescript-json-schema'; const generator = TJS.buildGenerator(program, settings);
import { buildGenerator } from 'typescript-json-schema';
The library primarily uses a namespace import (`* as TJS`) pattern for its core functions like `buildGenerator` and `getProgramFromFiles`. Destructured named imports may not work directly for all exports.
getProgramFromFiles
import * as TJS from 'typescript-json-schema'; const program = TJS.getProgramFromFiles(filePaths, compilerOptions, basePath);
const { getProgramFromFiles } = require('typescript-json-schema');
This library is primarily designed for TypeScript projects and uses ES module syntax. While CommonJS `require` might work with appropriate `esModuleInterop` settings in `tsconfig.json`, the idiomatic and type-safe approach is ES modules.
PartialArgs
import * as TJS from 'typescript-json-schema'; const settings: TJS.PartialArgs = { required: true };
Type imports are typically done via the same namespace import, accessing types as properties of the imported namespace. This ensures correct type resolution within TypeScript.

This quickstart demonstrates programmatic JSON Schema generation from a TypeScript interface using temporary files for demonstration. It configures the generator with common settings like `required` properties and `strictNullChecks` to produce a comprehensive schema, then prints it to the console.

import * as TJS from 'typescript-json-schema'; import { resolve } from 'path'; import * as fs from 'fs'; // Define your TypeScript interface or type const typeScriptCode = ` export interface User { id: number; name: string; email?: string; isActive: boolean; roles: ('admin' | 'user')[]; createdAt: Date; } `; const tempFilePath = resolve(__dirname, 'temp.ts'); fs.writeFileSync(tempFilePath, typeScriptCode); // Optionally pass argument to schema generator const settings: TJS.PartialArgs = { required: true, // Generate 'required' array for non-optional properties noExtraProps: true, // Disable additional properties in objects by default strictNullChecks: true, // Make values non-nullable by default titles: true, // Create titles in the output schema }; // Optionally pass ts compiler options const compilerOptions: TJS.CompilerOptions = { strictNullChecks: true, esModuleInterop: true, }; // Get a TypeScript Program from the file const program = TJS.getProgramFromFiles( [tempFilePath], compilerOptions, __dirname // Base path for the program ); // Build the schema generator const generator = TJS.buildGenerator(program, settings); // Generate the schema for a specific type (e.g., 'User') const schema = generator?.getSchemaForSymbol('User'); if (schema) { console.log(JSON.stringify(schema, null, 2)); } else { console.error('Failed to generate schema for User.'); } // Clean up the temporary file fs.unlinkSync(tempFilePath);
typescript-json-schema --version
Debug
Known issues
deprecatedThe library is explicitly stated to be in 'maintenance mode', suggesting minimal new feature development and a slower pace for bug fixes. Users seeking a more actively developed or feature-rich solution are advised to consider alternatives.
fix
Evaluate alternatives like `ts-json-schema-generator` for projects requiring active development or advanced features.
affects: >=0.60.0
gotchaWhen using the programmatic API, ensure `TJS.getProgramFromFiles` is called with the correct file paths, compiler options, and a valid base path. Incorrect paths or configurations can lead to errors in type resolution or schema generation.
fix
Always use `path.resolve` for file paths and verify your `tsconfig.json` or `compilerOptions` align with your project setup. Ensure the `basePath` parameter is correctly set, often to `__dirname` or the project root.
affects: >=0.1.0
gotchaDefault behavior for `additionalProperties` is `true` unless explicitly set to `false` via `--noExtraProps` option (CLI) or `noExtraProps: true` in settings (programmatic API). This can lead to less strict schemas than intended.
fix
Set `noExtraProps: true` in your generator settings if you want objects to disallow properties not explicitly defined in the TypeScript interface/type.
affects: >=0.1.0
gotchaThe library uses JSDoc annotations for certain schema features, but some require specific prefixes (e.g., `@TJS-type` instead of `@type`) due to TypeScript compiler limitations.
fix
Refer to the library's API documentation for the correct JSDoc annotation syntax, especially for overriding inferred types or adding custom keywords.
affects: >=0.1.0
Errors
Common errors & fixes
Error: ENOENT: no such file or directory, stat 'path/to/tsconfig.json'
The provided `tsconfig.json` path or input TypeScript file path is incorrect or the file does not exist.
fix
Verify the absolute path to your `tsconfig.json` or `.ts` files. Use `path.resolve()` for robustness. Ensure the files are accessible from where the script is run.
Symbol 'MyType' not found in program.
The specified TypeScript type or interface name (`MyType`) does not exist in the provided TypeScript program or is not exported.
fix
Double-check the type name for typos and ensure the type is correctly defined and exported in the TypeScript files included in the `getProgramFromFiles` call.
TypeError: Cannot read properties of undefined (reading 'getSchemaForSymbol')
The `generator` object is `null` or `undefined`, typically because `TJS.buildGenerator` failed to initialize due to issues with the TypeScript program or settings.
fix
Inspect the `program` object returned by `TJS.getProgramFromFiles` for errors. Ensure `filePaths` and `compilerOptions` are valid. Log the `generator` to see if it was successfully created.
Upgrade
Version history
0.67.1latest on npm
Audit
Dependencies
typescriptrequiredRequired for compiling TypeScript programs to extract type information for schema generation.
Agent activity
7 hits · last 30 days
node
6
OpenAI (training)
1
Resources
typescript-json-schema — npm install typescript-json-schema · libregistry