{"id":12238,"library":"typescript-json-schema","title":"TypeScript JSON Schema Generator","description":"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.","status":"maintenance","version":"0.67.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/YousefED/typescript-json-schema","tags":["javascript","typescript","json","forms","jsonschema","schema"],"install":[{"cmd":"npm install typescript-json-schema","lang":"bash","label":"npm"},{"cmd":"yarn add typescript-json-schema","lang":"bash","label":"yarn"},{"cmd":"pnpm add typescript-json-schema","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for compiling TypeScript programs to extract type information for schema generation.","package":"typescript","optional":false}],"imports":[{"note":"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.","wrong":"import { buildGenerator } from 'typescript-json-schema';","symbol":"buildGenerator","correct":"import * as TJS from 'typescript-json-schema'; const generator = TJS.buildGenerator(program, settings);"},{"note":"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.","wrong":"const { getProgramFromFiles } = require('typescript-json-schema');","symbol":"getProgramFromFiles","correct":"import * as TJS from 'typescript-json-schema'; const program = TJS.getProgramFromFiles(filePaths, compilerOptions, basePath);"},{"note":"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.","symbol":"PartialArgs","correct":"import * as TJS from 'typescript-json-schema'; const settings: TJS.PartialArgs = { required: true };"}],"quickstart":{"code":"import * as TJS from 'typescript-json-schema';\nimport { resolve } from 'path';\nimport * as fs from 'fs';\n\n// Define your TypeScript interface or type\nconst typeScriptCode = `\n  export interface User {\n    id: number;\n    name: string;\n    email?: string;\n    isActive: boolean;\n    roles: ('admin' | 'user')[];\n    createdAt: Date;\n  }\n`;\n\nconst tempFilePath = resolve(__dirname, 'temp.ts');\nfs.writeFileSync(tempFilePath, typeScriptCode);\n\n// Optionally pass argument to schema generator\nconst settings: TJS.PartialArgs = {\n  required: true, // Generate 'required' array for non-optional properties\n  noExtraProps: true, // Disable additional properties in objects by default\n  strictNullChecks: true, // Make values non-nullable by default\n  titles: true, // Create titles in the output schema\n};\n\n// Optionally pass ts compiler options\nconst compilerOptions: TJS.CompilerOptions = {\n  strictNullChecks: true,\n  esModuleInterop: true,\n};\n\n// Get a TypeScript Program from the file\nconst program = TJS.getProgramFromFiles(\n  [tempFilePath],\n  compilerOptions,\n  __dirname // Base path for the program\n);\n\n// Build the schema generator\nconst generator = TJS.buildGenerator(program, settings);\n\n// Generate the schema for a specific type (e.g., 'User')\nconst schema = generator?.getSchemaForSymbol('User');\n\nif (schema) {\n  console.log(JSON.stringify(schema, null, 2));\n} else {\n  console.error('Failed to generate schema for User.');\n}\n\n// Clean up the temporary file\nfs.unlinkSync(tempFilePath);\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Evaluate alternatives like `ts-json-schema-generator` for projects requiring active development or advanced features.","message":"The 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.","severity":"deprecated","affected_versions":">=0.60.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Set `noExtraProps: true` in your generator settings if you want objects to disallow properties not explicitly defined in the TypeScript interface/type.","message":"Default 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Refer to the library's API documentation for the correct JSDoc annotation syntax, especially for overriding inferred types or adding custom keywords.","message":"The 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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The provided `tsconfig.json` path or input TypeScript file path is incorrect or the file does not exist.","error":"Error: ENOENT: no such file or directory, stat 'path/to/tsconfig.json'"},{"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.","cause":"The specified TypeScript type or interface name (`MyType`) does not exist in the provided TypeScript program or is not exported.","error":"Symbol 'MyType' not found in program."},{"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.","cause":"The `generator` object is `null` or `undefined`, typically because `TJS.buildGenerator` failed to initialize due to issues with the TypeScript program or settings.","error":"TypeError: Cannot read properties of undefined (reading 'getSchemaForSymbol')"}],"ecosystem":"npm"}