tessl/npm-ts-json-schema-generator

Generate JSON schema from your TypeScript sources with extensive customization options

—

Pending

Overview

Eval results

Files

Schema Generation

Name: tessl/npm-ts-json-schema-generator
Author: tessl

Core functionality for generating JSON schemas from TypeScript types with extensive configuration options and advanced TypeScript feature support.

Capabilities

SchemaGenerator Class

Main class that orchestrates the schema generation process from TypeScript AST to JSON Schema.

class SchemaGenerator {
  constructor(
    program: ts.Program,
    nodeParser: NodeParser,
    typeFormatter: TypeFormatter,
    config?: Config
  );
  
  /**
   * Generate schema for a specific type or all exported types
   * @param fullName - Type name to generate schema for, or "*" for all types
   * @returns Complete JSON Schema object
   */
  createSchema(fullName?: string): Schema;
  
  /**
   * Generate schema from specific AST nodes
   * @param rootNodes - Array of TypeScript AST nodes to process
   * @returns Complete JSON Schema object
   */
  createSchemaFromNodes(rootNodes: ts.Node[]): Schema;
}

Usage Examples:

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

// Generate schema for specific type
const config = {
  path: "src/types.ts",
  type: "User"
};
const generator = createGenerator(config);
const userSchema = generator.createSchema("User");

// Generate schema for all exported types
const allTypesConfig = {
  path: "src/**/*.ts",
  type: "*"
};
const allSchema = createGenerator(allTypesConfig).createSchema("*");

Factory Function

Main entry point for creating configured SchemaGenerator instances.

/**
 * Create a fully configured SchemaGenerator instance
 * @param config - Configuration object for schema generation
 * @returns Configured SchemaGenerator instance
 */
function createGenerator(config: Config): SchemaGenerator;

Configuration Interface

Complete configuration interface controlling all aspects of schema generation.

interface Config {
  /** Source file path or glob pattern */
  path?: string;
  /** Type name to generate schema for, or "*" for all types */
  type?: string;  
  /** Custom TSConfig file path */
  tsconfig?: string;
  /** Control which types are included in schema */
  expose?: "all" | "none" | "export";
  /** JSDoc annotation processing level */
  jsDoc?: "none" | "extended" | "basic";
  /** Minify the generated schema */
  minify?: boolean;
  /** Sort object properties alphabetically */
  sortProps?: boolean;
  /** Enforce strict tuple types without additional items */
  strictTuples?: boolean;
  /** Skip TypeScript type checking for faster generation */
  skipTypeCheck?: boolean;
  /** Encode $ref paths for compatibility */
  encodeRefs?: boolean;
  /** Include top-level $ref definition */
  topRef?: boolean;
  /** Generate markdownDescription in addition to description */
  markdownDescription?: boolean;
  /** Additional validation keywords to include */
  extraTags?: string[];
  /** Allow additional properties for objects without index signatures */
  additionalProperties?: boolean;
  /** How to handle function types */
  functions?: "fail" | "comment" | "hide";
  /** Schema $id value */
  schemaId?: string;
  /** Discriminator handling mode */
  discriminatorType?: "json-schema" | "open-api";
}

Configuration Examples:

// Minimal config for quick generation
const simpleConfig: Config = {
  path: "src/api.ts",
  type: "ApiResponse"
};

// Full config with all options
const advancedConfig: Config = {
  path: "src/**/*.ts",
  type: "*",
  tsconfig: "./tsconfig.json",
  expose: "export",
  jsDoc: "extended", 
  minify: false,
  sortProps: true,
  strictTuples: true,
  skipTypeCheck: false,
  encodeRefs: true,
  topRef: true,
  markdownDescription: true,
  extraTags: ["format", "pattern"],
  additionalProperties: false,
  functions: "comment",
  schemaId: "https://example.com/my-schema",
  discriminatorType: "json-schema"
};

Default Configuration

Default values used when configuration options are not specified.

const DEFAULT_CONFIG: Omit<Required<Config>, "path" | "type" | "schemaId" | "tsconfig"> = {
  expose: "export",
  topRef: true,
  jsDoc: "extended",
  markdownDescription: false,
  sortProps: true,
  strictTuples: false,
  skipTypeCheck: false,
  encodeRefs: true,
  minify: false,
  extraTags: [],
  additionalProperties: false,
  discriminatorType: "json-schema",
  functions: "comment"
};

type CompletedConfig = Config & typeof DEFAULT_CONFIG;

Schema and Definition Types

Type aliases for JSON Schema structures.

import type { JSONSchema7 } from "json-schema";

/** Complete JSON Schema object */
type Schema = JSONSchema7;

/** JSON Schema definition for types and properties */
type Definition = JSONSchema7;

Generated Schema Example:

// Input TypeScript type
interface User {
  id: number;
  name: string;
  email?: string;
  roles: ("admin" | "user")[];
}

// Generated JSON Schema
const userSchema = {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": { "type": "number" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "roles": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["admin", "user"]
      }
    }
  },
  "required": ["id", "name", "roles"],
  "additionalProperties": false
};

Function Options

Control how function types are handled during schema generation.

type FunctionOptions = "fail" | "comment" | "hide";

"fail": Throws an error when encountering function types
"comment": Adds a comment describing the function signature
"hide": Treats functions like NeverType or HiddenType (excludes from schema)

Install with Tessl CLI

npx tessl i tessl/npm-ts-json-schema-generator

docs

program-management.md

schema-generation.md

type-formatting.md

tile.json

tessl/npm-ts-json-schema-generator