JSON Schema to TypeScript (Forked)

Common errors

• Error: Cannot find module 'json-schema-to-typescript'

  cause The package `rm-json-schema-to-typescript` is installed, but the import path in the code might be incorrect or the module resolver cannot find the aliased module.
  fix Ensure `rm-json-schema-to-typescript` is correctly installed. Based on the documentation, try `import { compile } from 'json-schema-to-typescript'` even if you installed the `rm-` prefixed package. Verify your `tsconfig.json` or module resolution settings if problems persist.

• TypeError: Schema must be an object or boolean

  cause The input provided to `compile` or `compileFromFile` is not a valid JSON Schema object or a path to a valid JSON Schema file.
  fix Validate your JSON Schema against the JSON Schema specification (e.g., using a linter or online validator) to ensure it is correctly structured. Check the file path for `compileFromFile`.

• Error: $ref cycle detected

  cause The JSON schema contains circular `$ref`erences that the parser cannot resolve, or the `cwd` option for resolving external references is incorrect.
  fix Review the `$ref` definitions in your JSON schema for circular dependencies. If using external `$ref`s, ensure the `cwd` option in `compile` or `compileFromFile` options correctly points to the base directory for resolution.

Warnings

• deprecated This `rm-json-schema-to-typescript` package is a fork and is explicitly slated for deprecation once its specific changes are accepted into the upstream `json-schema-to-typescript` project. Users should treat it as a temporary solution and plan for migration.
  Fix: Monitor the original `json-schema-to-typescript` project for updates that incorporate the `rm-json-schema-to-typescript` fork's features. If no upstream merge occurs, consider migrating to another active JSON Schema to TypeScript solution or maintaining a custom fork.
• gotcha This fork specifically features 'changed reference resolving' compared to the original `json-schema-to-typescript`. This modification may lead to different output typings for schemas that rely on complex `$ref` patterns.
  Fix: Thoroughly review generated TypeScript types if migrating from or to the original `json-schema-to-typescript` package, especially for schemas with external or complex internal `$ref`erences. Test the output against expected type definitions.
• gotcha Despite the npm package name being `rm-json-schema-to-typescript`, the provided documentation and code examples suggest importing symbols from `'json-schema-to-typescript'`. This discrepancy can cause confusion and potential module resolution errors if not handled correctly.
  Fix: When installing via npm as `rm-json-schema-to-typescript`, ensure your import statements in code use `import { ... } from 'json-schema-to-typescript'` as per the documentation. If issues arise, explicitly check your project's module resolution settings or the `package.json` `exports` field of the installed package.

Install

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

Imports

• compile
  wrong:

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

  correct:

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

  The npm package is `rm-json-schema-to-typescript`, but the import path shown in the provided documentation is `json-schema-to-typescript`. This implies it's a drop-in replacement using the original's module name. Always verify the actual import path for the installed package.
• compileFromFile
  wrong:

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

  correct:

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

  Similar to `compile`, the import path refers to the original package name. Ensure your `package.json` correctly points to `rm-json-schema-to-typescript` if using this fork.
• Options

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

  Type imports for configuration options are available. The options object can modify behavior like banner comments, `$ref` resolution, or Prettier formatting.

Quickstart

This quickstart demonstrates how to compile a JSON schema object into a TypeScript interface using the `compile` function, and how it writes the output to a file.

import { compile, compileFromFile } from 'json-schema-to-typescript';
import * as fs from 'fs/promises';

// Define a simple JSON schema programmatically
const mySchema = {
  title: 'UserSchema',
  type: 'object',
  properties: {
    id: { type: 'string', format: 'uuid' },
    name: { type: 'string' },
    email: { type: 'string', format: 'email' },
    isActive: { type: 'boolean', default: true }
  },
  required: ['id', 'name', 'email'],
  additionalProperties: false
};

async function generateTypes() {
  try {
    // Compile from a JS object in memory
    const tsFromObject = await compile(mySchema, 'UserSchema');
    console.log('Generated from object:\n', tsFromObject);
    // For demonstration, write to a dummy file. In real use, this might be dynamic.
    await fs.writeFile('user.d.ts', tsFromObject);

    // Example of compiling from a file (assuming 'example.json' exists)
    // For a real scenario, you'd create this file first.
    // const tsFromFile = await compileFromFile('example.json');
    // await fs.writeFile('example.d.ts', tsFromFile);

    console.log('TypeScript types generated successfully.');
  } catch (error) {
    console.error('Error generating types:', error);
  }
}

generateTypes();