TypeScript JSON Schema Generator

Common errors

• Error: ENOENT: no such file or directory, stat 'path/to/tsconfig.json'

  cause 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.

  cause 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')

  cause 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.

Warnings

• deprecated 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.
  Fix: Evaluate alternatives like `ts-json-schema-generator` for projects requiring active development or advanced features.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Set `noExtraProps: true` in your generator settings if you want objects to disallow properties not explicitly defined in the TypeScript interface/type.
• gotcha 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.
  Fix: Refer to the library's API documentation for the correct JSDoc annotation syntax, especially for overriding inferred types or adding custom keywords.

Install

• npm install typescript-json-schema npm
• yarn add typescript-json-schema yarn
• pnpm add typescript-json-schema pnpm

Imports

• buildGenerator
  wrong:

  import { buildGenerator } from 'typescript-json-schema';

  correct:

  import * as TJS from 'typescript-json-schema'; const generator = TJS.buildGenerator(program, settings);

  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
  wrong:

  const { getProgramFromFiles } = require('typescript-json-schema');

  correct:

  import * as TJS from 'typescript-json-schema'; const program = TJS.getProgramFromFiles(filePaths, compilerOptions, basePath);

  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.

Quickstart

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);