TypeScript JSON Schema Generator

Common errors

• Error: Type 'MyType' not found in file 'path/to/my-file.ts'.

  cause The specified type name is incorrect, not exported, or the file path/tsconfig.json configuration is preventing the generator from finding it.
  fix Double-check the type name for typos, ensure the type is `export`ed, and verify that the `path` and `tsconfig` settings correctly point to the file and project configuration.

• Error: Unknown node 'SyntaxKind.JsxElement' (or similar 'SyntaxKind.OtherExpression', 'SyntaxKind.BinaryExpression').

  cause The generator encountered an unsupported or unusually complex TypeScript AST node, often from external libraries or highly specialized syntax.
  fix Simplify the TypeScript types involved, especially if they are heavily reliant on external JSX elements, complex expressions, or library-specific patterns. Consider creating simpler interfaces that derive from or represent the core data structure.

• TS2300: Duplicate identifier 'Headers'.

  cause This usually indicates a conflict in type definitions, often due to multiple `lib` configurations in `tsconfig.json` or conflicting `@types` packages.
  fix Review your `tsconfig.json`'s `compilerOptions.lib` setting to ensure it doesn't include redundant or conflicting DOM/ES environments. Check for duplicate `@types` dependencies.

• Error: Parameter 'files' must be an array of strings

  cause When using the CLI with a wildcard in the `--path` argument, the shell expanded the wildcard, leading the generator to receive multiple arguments instead of a single quoted string.
  fix Ensure that any paths containing wildcards (`*`) passed to the CLI via `--path` are enclosed in single or double quotes, e.g., `npx ts-json-schema-generator --path 'src/**/*.ts' ...`.

Warnings

• gotcha Only exported types, interfaces, and enums are exposed in the definitions section of the generated JSON schema. Types not explicitly exported will not be included or referenced.
  Fix: Ensure all TypeScript types and interfaces you intend to generate schemas for are exported from their respective files.
• gotcha When using the CLI with path wildcards (e.g., `--path 'src/**/*.ts'`), it's crucial to quote the path. Without quotes, the shell might expand the wildcard, passing only the first matching file to the generator instead of the pattern, leading to incomplete schema generation.
  Fix: Always quote paths containing wildcards in your CLI commands, e.g., `npx ts-json-schema-generator --path 'src/**/*.ts' --type 'MyType'`.
• gotcha Complex TypeScript constructs, especially intricate generics, mapped types, or types from large third-party libraries (e.g., React, Node.js `lib.d.ts`), can sometimes lead to 'Unknown node' errors or incomplete/incorrect schema output.
  Fix: Try simplifying the TypeScript types where possible. For external library types, consider creating a simpler alias or a subset interface that only includes the properties relevant for your schema generation. Report specific issues on GitHub.
• gotcha The behavior of `additionalProperties` for objects without index signatures can be unexpected. By default, it's often `false`, meaning properties not explicitly defined in the schema are disallowed. This might not align with intended 'open' objects.
  Fix: Explicitly control `additionalProperties` via the configuration option (`additionalProperties: true` or `false`) or use JSDoc annotations (`@additionalProperties true` / `@additionalProperties false`) on your TypeScript types.
• gotcha Incorrect or missing `tsconfig.json` configuration can lead to TypeScript compiler errors during schema generation, such as 'Cannot find module' or 'Duplicate identifier'. Ensure the `tsconfig.json` correctly includes all source files and specifies appropriate `lib` options.
  Fix: Verify that the `path` and `tsconfig` options in your configuration (or CLI arguments) correctly point to your source files and project's `tsconfig.json`. Adjust `compilerOptions.lib` in `tsconfig.json` if encountering 'Duplicate identifier' errors, especially with built-in types like `DOM` or `ESNext`.

Install

• npm install ts-json-schema-generator npm
• yarn add ts-json-schema-generator yarn
• pnpm add ts-json-schema-generator pnpm

Imports

• createGenerator
  wrong:

  const createGenerator = require('ts-json-schema-generator').createGenerator;

  correct:

  import { createGenerator } from 'ts-json-schema-generator';

  This is the primary function for programmatic schema generation. The CommonJS `require` pattern is generally discouraged in modern TypeScript projects.
• Config
  wrong:

  import { Config } from 'ts-json-schema-generator'; // Importing a type as a value

  correct:

  import type { Config } from 'ts-json-schema-generator';

  The `Config` interface defines the configuration options for `createGenerator`. It should be imported as a type for type safety without bundling overhead. Older CommonJS examples might import it from a deep path like `dist/src/Config`.
• Schema

  import type { Schema } from 'ts-json-schema-generator';

  Represents the generated JSON Schema object. Primarily used for type annotation, so `import type` is appropriate.

Quickstart

Demonstrates programmatic generation of a JSON schema for a specific TypeScript interface using a local `tsconfig.json`.

import { createGenerator } from 'ts-json-schema-generator';
import * as fs from 'fs';
import * as path from 'path';

// 1. Define your TypeScript types in a file, e.g., 'src/types.ts'
// export interface User {
//   id: string;
//   name: string;
//   email?: string;
//   isActive: boolean;
//   roles: Array<'admin' | 'editor' | 'viewer'>;
//   createdAt: Date;
// }

// 2. Configure the generator
const config = {
  path: path.resolve(__dirname, 'src/types.ts'),
  tsconfig: path.resolve(__dirname, 'tsconfig.json'),
  type: 'User', // Specify the type name to generate schema for
  skipTypeCheck: false, // Set to true for faster generation, but less strict validation
  additionalProperties: true, // Allow undeclared properties by default (matches JSON Schema spec more loosely)
};

// 3. Ensure a tsconfig.json exists for the project
// {
//   "compilerOptions": {
//     "target": "ES2022",
//     "module": "NodeNext",
//     "strict": true,
//     "esModuleInterop": true,
//     "skipLibCheck": true,
//     "forceConsistentCasingInFileNames": true
//   },
//   "include": ["src/**/*.ts"]
// }

// 4. Generate the schema
try {
  const schemaGenerator = createGenerator(config);
  const schema = schemaGenerator.createSchema(config.type);

  const outputPath = path.resolve(__dirname, 'generated/user.schema.json');
  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
  fs.writeFileSync(outputPath, JSON.stringify(schema, null, 2));

  console.log(`JSON Schema for type '${config.type}' generated successfully at ${outputPath}`);
} catch (error) {
  console.error('Failed to generate JSON schema:', error);
  process.exit(1);
}