json-schema-to-typescript vs typescript-json-schema: Direction Matters

At first glance, both json-schema-to-typescript and typescript-json-schema deal with the same two worlds: JSON Schema and TypeScript. But they solve opposite problems. Understanding which direction you’re moving in—schema → TS or TS → schema—is the key to picking the right tool.

🔄 Core Direction: Input vs Output

json-schema-to-typescript takes a JSON Schema object and outputs TypeScript type definitions.

// Input: JSON Schema (e.g., user.schema.json)
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "number" }
  },
  "required": ["name"]
}

// Output: Generated TypeScript
interface User {
  name: string;
  age?: number;
}

You’d typically run this as a build step:

// build-types.js
const fs = require('fs');
const { compile } = require('json-schema-to-typescript');

compile(fs.readFileSync('user.schema.json', 'utf8'), 'User')
  .then(ts => fs.writeFileSync('user.ts', ts));

typescript-json-schema takes TypeScript source files and outputs a JSON Schema object.

// Input: TypeScript (e.g., models.ts)
export interface User {
  name: string;
  age?: number;
}

You generate schema via CLI or API:

// build-schema.js
const { generateSchema } = require('typescript-json-schema');

const program = require('typescript').createProgram(['models.ts'], {});
const schema = generateSchema(program, 'User');
// schema is now a JSON Schema object

Or via command line:

npx typescript-json-schema tsconfig.json User --out user.schema.json

🛠️ Handling Complex Types

Both tools handle real-world complexity, but differently based on their direction.

Optional Properties & Unions

json-schema-to-typescript maps JSON Schema’s required array and anyOf/oneOf to optional properties and union types:

// schema.json
{
  "type": "object",
  "properties": {
    "status": { "enum": ["active", "inactive"] }
  },
  "required": []
}

Becomes:

interface MyObject {
  status?: "active" | "inactive";
}

typescript-json-schema converts TypeScript unions and optional fields back into equivalent JSON Schema:

// models.ts
interface ApiResponse {
  data?: string | number;
  error?: { message: string };
}

Generates:

{
  "type": "object",
  "properties": {
    "data": { "anyOf": [{ "type": "string" }, { "type": "number" }] },
    "error": {
      "type": "object",
      "properties": { "message": { "type": "string" } },
      "required": ["message"]
    }
  }
}

References and Reusability

json-schema-to-typescript resolves $ref pointers during compilation:

// main.schema.json
{
  "$ref": "./definitions.json#/User"
}

It inlines or generates separate interfaces based on options, producing flat or modular TS output.

typescript-json-schema follows TypeScript imports and type aliases:

// user.ts
import { Address } from './shared';

interface User {
  address: Address;
}

The resulting JSON Schema includes a definition for Address and references it correctly if enabled.

⚙️ Integration with Build Systems

json-schema-to-typescript is designed for frontend consumption. You often run it once during setup or as part of a CI pipeline to keep your types in sync with a backend schema. The output is meant to be committed to source control.

typescript-json-schema integrates tightly with the TypeScript compiler. It requires a valid tsconfig.json and parses your actual codebase. This makes it powerful for generating up-to-date schemas from evolving domain models, especially in monorepos.

🧪 Runtime Validation Scenarios

Suppose you use Ajv for runtime validation in your app.

• If your team owns the backend and defines types in TypeScript, use typescript-json-schema to emit JSON Schema, then share that schema with the frontend for validation.

• If you’re a frontend team consuming a third-party API that publishes an OpenAPI spec (which includes JSON Schema), use json-schema-to-typescript to turn those schemas into TypeScript interfaces for Axios or Fetch wrappers.

📁 File I/O and Programmatic Use

Both support programmatic usage, but their APIs reflect their purpose.

json-schema-to-typescript:

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

compileFromFile('api.schema.json', {
  cwd: './schemas',
  bannerComment: ''
}).then(ts => console.log(ts));

typescript-json-schema:

const { createProgram, generateSchema } = require('typescript-json-schema');

const program = createProgram(['src/models.ts']);
const settings = { required: true };
const schema = generateSchema(program, 'Order', settings);

🚫 Common Pitfalls

• json-schema-to-typescript cannot infer types that don’t exist in the schema. If your JSON Schema lacks required fields, everything becomes optional—even if your API actually requires them.

• typescript-json-schema may struggle with highly dynamic or conditional types (e.g., Exclude<T, U> with complex generics). It works best with concrete interfaces and type aliases.

✅ When They Work Together

In mature architectures, you might use both:

1. Backend defines UserDTO in TypeScript.
2. typescript-json-schema generates user.schema.json.
3. Frontend consumes user.schema.json via json-schema-to-typescript to produce User.ts.
4. Both sides validate payloads at runtime using the same schema.

This creates a closed loop of type safety across the stack.

📊 Summary: Key Differences

💡 Final Guidance

Ask yourself: Where does my source of truth live?

• If it’s a JSON Schema document (from OpenAPI, Postman, or a spec), reach for json-schema-to-typescript.
• If it’s TypeScript code (your own models or DTOs), use typescript-json-schema.

Don’t try to force one tool to do the other’s job — they’re optimized for opposite workflows. Used correctly, either can eliminate entire classes of bugs caused by schema drift between client and server.