JSON Schema to TypeScript

Common errors

• Error: ENOENT: no such file or directory, open 'your-schema.json'

  cause The `compileFromFile` function was called with a file path that does not exist or is inaccessible.
  fix Verify that the path to your JSON Schema file is correct and that the file has appropriate read permissions. Ensure relative paths are resolved correctly, e.g., using `path.join(__dirname, 'your-schema.json')`.

• TypeError: (0, json_schema_to_typescript_1.compile) is not a function

  cause This error often indicates a CommonJS module trying to import an ESM-only package, or a bundling/transpilation issue where ES module exports are not correctly resolved.
  fix Ensure your project is configured for ES modules (e.g., `"type": "module"` in `package.json`) and that you are using `import { compile } from 'json-schema-to-typescript'` syntax. If running directly in Node.js, confirm your file uses `.mjs` extension or `type: module`.

• ReferenceError: require is not defined in ES module scope

  cause You are attempting to use `require()` in an ES module (`.mjs` file or `"type": "module"` project) where CommonJS `require` is not available.
  fix Refactor your imports to use ES module `import` syntax: `import { compile, compileFromFile } from 'json-schema-to-typescript'`. If you need conditional imports, consider dynamic `import()`.

• TS2411: Property 'x' of type 'string | undefined' is not assignable to string index type 'string'.

  cause This TypeScript error can occur when `additionalProperties` is implicitly or explicitly `true` in your schema, leading to `[k: string]: any` (or similar) but a property within `properties` is `undefined` due to `strictNullChecks`.
  fix Set `"additionalProperties": false` in your JSON Schema to disallow undeclared properties, or pass `{ additionalProperties: false }` to the `compile` options. Alternatively, if `additionalProperties` is desired, ensure all explicitly defined properties are not `undefined` or handle them appropriately.

Warnings

• breaking The default behavior for `additionalProperties` was changed in some versions, or its interpretation became stricter. Prior versions might have implicitly allowed additional properties, leading to `[k: string]: any` in generated types. Explicitly setting `additionalProperties` in your schema or via the library's options is highly recommended.
  Fix: Always explicitly define `additionalProperties` in your JSON Schema (`true`, `false`, or a sub-schema) or pass `{ additionalProperties: false }` (or `true`) in the `Options` object to `compile` or `compileFromFile` to ensure consistent behavior. For CLI, use `--no-additionalProperties` or `--additionalProperties`.
• breaking Handling of `oneOf`, `anyOf`, and `allOf` keywords can sometimes lead to `unknown` types or unexpected union types if the schema is ambiguous or complex. This has seen refinements across major versions to improve type precision, but might alter generated types for certain complex schemas.
  Fix: Carefully review schemas using `oneOf`/`anyOf`/`allOf`. Ensure they are unambiguous and provide clear type inference paths. Consider using `discriminator` if applicable for `oneOf` to guide type inference. If `unknown` types appear, simplify the schema or add `tsType` annotations (custom schema properties) as a workaround.
• gotcha Performance issues can occur when processing very large or deeply nested JSON Schemas, especially with the default code formatting enabled (which uses Prettier internally).
  Fix: For large schemas, set `format: false` in the options object (`{ format: false }`) to disable internal Prettier formatting, then apply formatting manually if needed. For CLI, use `--no-format`.
• deprecated Older versions of the library or specific forks might have different default behaviors or removed features, such as `json-schema-to-typescript-lite` removing CLI support and Prettier integration for a lighter footprint.
  Fix: Always refer to the documentation for your specific installed version. For the main `json-schema-to-typescript` package, upgrading to the latest stable version (currently 15.x) is recommended for the most current features and fixes.
• gotcha The library relies on `fs` for file operations (`compileFromFile`), which is a Node.js-specific module. Direct use of `compileFromFile` in a browser environment will fail.
  Fix: When using `json-schema-to-typescript` in a browser environment, use the `compile` function with an in-memory JSON Schema object. You will need to fetch the schema content separately if it resides on a server.

Install

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

Imports

• compile
  wrong:

  const { compile } = require('json-schema-to-typescript')

  correct:

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

  The library primarily uses ES module imports. While `require` might work in some transpiled environments, `import` is the idiomatic and recommended way for modern Node.js and TypeScript projects.
• compileFromFile
  wrong:

  const { compileFromFile } = require('json-schema-to-typescript')

  correct:

  import { compileFromFile } from 'json-schema-to-typescript'

  Used for reading JSON Schema directly from a file path. Ensure your project is configured for ES modules.
• JSONSchema

  import type { JSONSchema } from 'json-schema-to-typescript'

  This is a type-only import for the internal JSONSchema type used by the library, useful for strongly typing schema objects in your code. Use `import type` to ensure it's erased at runtime.

Quickstart

This quickstart demonstrates how to programmatically compile a JSON Schema to TypeScript types, both from an in-memory object and from a file, using common configuration options. It creates a temporary `schema.json` and outputs `types.d.ts`.

import { compile, Options } from 'json-schema-to-typescript';
import * as fs from 'node:fs/promises';
import * as path from 'node:path';

async function generateTypes() {
  const schemaPath = path.join(process.cwd(), 'schema.json');
  const outputPath = path.join(process.cwd(), 'types.d.ts');

  const mySchema = {
    "title": "UserProfile",
    "description": "A schema for user profile data",
    "type": "object",
    "properties": {
      "id": { "type": "string", "format": "uuid" },
      "username": { "type": "string", "minLength": 3, "maxLength": 20 },
      "email": { "type": "string", "format": "email" },
      "age": { "type": "integer", "minimum": 0, "maximum": 120 },
      "isActive": { "type": "boolean", "default": true }
    },
    "required": ["id", "username", "email"]
  };

  // Save schema to a file for compileFromFile example (optional, but good for demo)
  await fs.writeFile(schemaPath, JSON.stringify(mySchema, null, 2));

  const options: Partial<Options> = {
    bannerComment: "/* eslint-disable */\n/** Automatically generated from JSON Schema */",
    additionalProperties: false,
    unreachableDefinitions: true
  };

  try {
    // Example 1: Compile from an in-memory JS object
    const tsFromObject = await compile(mySchema, 'UserProfile', options);
    console.log('Generated from object:\n', tsFromObject);

    // Example 2: Compile from a file
    const tsFromFile = await compileFromFile(schemaPath, options);
    await fs.writeFile(outputPath, tsFromFile);
    console.log(`Types generated to ${outputPath}`);
  } catch (error) {
    console.error('Error generating types:', error);
  }
}

generateTypes();