JSON Schema to TypeScript (Lite)

15.0.0 · active · verified Sun Apr 19

json-schema-to-typescript-lite is a focused fork of json-schema-to-typescript, designed to compile JSON schemas into TypeScript typings with a significantly reduced dependency footprint. The current stable version is 15.0.0. This package emphasizes programmatic usage, foregoing CLI support and internal Prettier integrations for a leaner build. It achieves smaller bundle sizes by replacing heavy dependencies like `lodash` with `lodash-es` (bundled) and targets modern ESNext environments. It offers dual module support (ESM and CJS) and includes support for custom naming options, making it suitable for environments where bundle size and minimal dependencies are critical considerations.

Common errors

```
Error: Cannot find module 'json-schema-to-typescript-lite'
```
cause The package is not installed or the import path is incorrect.

fix Ensure the package is installed: `npm install json-schema-to-typescript-lite` or `yarn add json-schema-to-typescript-lite`. Verify the import statement is `import { compile } from 'json-schema-to-typescript-lite';`.
```
Schema validation failed
```
cause The provided JSON schema is not a valid JSON Schema Draft 04/06/07.

fix Review your JSON schema against the specification. Common issues include incorrect `type` definitions, missing `properties` or `items` for array/object types, or invalid keywords.
```
TypeError: Cannot read properties of undefined (reading 'type')
```
cause You likely passed an `undefined` or `null` value instead of a valid JSON schema object to the `compile` function.

fix Ensure the first argument passed to `compile` is a valid, non-null JSON schema object.

Warnings

breaking CLI support has been completely removed. This package is strictly for programmatic usage.
Fix: Migrate any CLI usage to direct programmatic calls to the `compile` function within your build scripts or application.
breaking Internal Prettier integration has been removed. The package now generates well-formatted code by default, but external formatting is required if specific Prettier rules are desired.
Fix: Run Prettier as a separate step on the generated TypeScript output if custom formatting is necessary.
breaking Dependencies like `lodash` have been replaced with lighter alternatives or bundled (`lodash-es`). While improving bundle size, this means any explicit dependency on these from the original `json-schema-to-typescript` will no longer be satisfied by this 'lite' fork.
Fix: Review your project's dependencies and explicitly add any external libraries that were implicitly provided by the non-lite version.
gotcha This is a 'lite' fork. While it aims for similar core functionality, subtle behavioral differences might exist due to dependency changes or optimizations not present in the main `json-schema-to-typescript` package.
Fix: Thoroughly test your schema compilation output when migrating from `json-schema-to-typescript` to `json-schema-to-typescript-lite`.

Install

npm install json-schema-to-typescript-lite npm
yarn add json-schema-to-typescript-lite yarn
pnpm add json-schema-to-typescript-lite pnpm

Imports

compile
wrong:
```
const compile = require('json-schema-to-typescript-lite');
```
correct:
```
import { compile } from 'json-schema-to-typescript-lite';
```
The primary function for compiling a JSON schema to a TypeScript string. Supports both ESM and CJS, but ESM import is preferred in modern Node.js/browser environments.
compile (default import incorrect)
wrong:
```
import compile from 'json-schema-to-typescript-lite';
```
correct:
```
import { compile } from 'json-schema-to-typescript-lite';
```
The 'compile' function is a named export, not a default export.
Type definitions
```
import type { JSONSchema4, Options } from 'json-schema-to-typescript-lite';
```
While `Options` and schema types are available for type hinting, they are not always explicitly imported for basic usage.

Quickstart

Demonstrates basic usage of `compile` to convert a JSON schema object into a TypeScript interface string, including common options.

import { compile } from 'json-schema-to-typescript-lite';

async function generateUserTypes() {
  const userSchema = {
    type: 'object',
    properties: {
      id: { type: 'string', description: 'Unique user identifier' },
      name: { type: 'string', minLength: 1 },
      email: { type: 'string', format: 'email' },
      age: { type: 'number', minimum: 0, maximum: 120 },
      isActive: { type: 'boolean', default: true },
      roles: {
        type: 'array',
        items: { type: 'string', enum: ['admin', 'editor', 'viewer'] },
        minItems: 1
      }
    },
    required: ['id', 'name', 'email', 'isActive'],
    additionalProperties: false,
    title: 'UserSchema', // Used as base name if not overridden by second arg
    description: 'Defines the structure for a user object.'
  };

  try {
    const tsDefinition = await compile(userSchema, 'IUser', {
      bannerComment: '/* Generated by json-schema-to-typescript-lite */',
      declareExternallyReferenced: false,
      unknownAny: false, // Prefer 'unknown' over 'any'
      customName: (id: string) => id === 'IUser' ? 'MyCustomUserType' : id,
    });
    console.log(tsDefinition);
  } catch (error) {
    console.error('Failed to compile schema:', error);
  }
}

generateUserTypes().catch(console.error);

view raw JSON →