JSON Schema to TypeScript Type Inferer

3.1.1 · active · verified Sun Apr 19

json-schema-to-ts is a TypeScript library designed to infer static TypeScript types directly from existing JSON schemas. This eliminates the need for manual type duplication, mitigating potential bugs and reducing maintenance overhead in projects that rely on JSON schemas for runtime data validation. The current stable version is 3.1.1, with a release cadence that is quite active, typically seeing minor or patch updates on a monthly basis. A key differentiator from libraries like Zod, Yup, or Runtypes is its focus purely on type inference from the established JSON Schema standard, rather than providing an integrated validation and schema definition system. This makes it an ideal choice for development environments where JSON schemas are already a primary source of truth for API specifications (e.g., OpenAPI) or data contracts, enabling seamless integration of existing schemas for robust static type checking.

Common errors

```
Argument of type '{ type: string; properties: { name: { type: string; }; }; required: string[]; }' is not assignable to parameter of type 'JSONSchema'.
```
cause The schema object is not asserted as `const`, causing TypeScript to widen its literal types. `FromSchema` expects a 'const' type.

fix Add `as const` to your schema definition: `const mySchema = { ... } as const;`.
```
A 'const' assertion can only be applied to a string, number, boolean, array, or object literal.
```
cause You are trying to apply `as const` to a non-literal expression, such as an imported JSON file that isn't cast as a literal, or a function return value.

fix Ensure `as const` is applied directly to an object literal. If importing JSON, you might need a runtime assertion or convert it to a TypeScript literal type.
```
The 'satisfies' operator is only available in TypeScript version 4.9 or newer.
```
cause Your `tsconfig.json` targets a TypeScript version older than 4.9, which does not support the `satisfies` operator.

fix Update your `typescript` dependency in `package.json` and your `tsconfig.json` settings to use TypeScript 4.9 or newer.

Warnings

breaking In version 3.0.0, the type inference for properties with a `default` keyword changed. Previously, defaulted properties were inferred as optional (`?`). Since v3.0.0, they are inferred as required (`:`).
Fix: Review schemas with `default` properties. If the property should remain optional in the TypeScript type, explicitly mark it as optional in the schema using `"required": [...]` and omitting the property name, or adjust your types where the property is used.
gotcha Forgetting the `as const` assertion on your JSON schema object will lead to TypeScript widening the types, resulting in less precise or incorrect inferred types (e.g., `"string"` becoming `string`, `"true"` becoming `boolean`).
Fix: Always append `as const` to your schema definitions (e.g., `const mySchema = { ... } as const;`). Alternatively, use the `asConst` utility function provided by the library or the TypeScript 4.9+ `satisfies` operator.
gotcha The `satisfies` operator, a modern alternative to `as const` for type-checking schemas, requires TypeScript version 4.9 or newer. Using it with older versions will result in a syntax error.
Fix: Upgrade your TypeScript version to 4.9 or higher, or use the `as const` assertion or the `asConst` utility function instead.

Install

npm install json-schema-to-ts npm
yarn add json-schema-to-ts yarn
pnpm add json-schema-to-ts pnpm

Imports

FromSchema
wrong:
```
import FromSchema from 'json-schema-to-ts'
```
correct:
```
import { FromSchema } from 'json-schema-to-ts'
```
FromSchema is a named export, primarily used as a type. Always use `typeof` with your schema object when passing it to FromSchema.
asConst
wrong:
```
const schema = asConst({...})
```
correct:
```
import { asConst } from 'json-schema-to-ts'
```
asConst is a runtime utility function to help TypeScript infer a 'const' type for schemas, an alternative to the `as const` assertion.
JSONSchema
wrong:
```
import { JSONSchema } from 'json-schema-to-ts'
```
correct:
```
import type { JSONSchema } from 'json-schema-to-ts'
```
JSONSchema is a type representing a valid JSON Schema object. Use `import type` as it's a type-only import, commonly used with the `satisfies` operator.

Quickstart

This quickstart demonstrates how to define a JSON schema and infer its TypeScript type using `FromSchema`, along with how to instantiate an object conforming to that type.

import { FromSchema } from 'json-schema-to-ts';

const userSchema = {
  type: 'object',
  properties: {
    id: { type: 'string', format: 'uuid' },
    name: { type: 'string' },
    email: { type: 'string', format: 'email' },
    age: { type: 'integer', minimum: 0 },
    isActive: { type: 'boolean', default: true },
    roles: { type: 'array', items: { enum: ['admin', 'editor', 'viewer'] } },
  },
  required: ['id', 'name', 'email', 'age'],
  additionalProperties: false,
} as const;

type User = FromSchema<typeof userSchema>;

const newUser: User = {
  id: 'a1b2c3d4-e5f6-7890-1234-567890abcdef',
  name: 'Jane Doe',
  email: 'jane.doe@example.com',
  age: 30,
  // isActive will be inferred as boolean and optional due to default, but is required by v3 behavior for defaulted properties.
  roles: ['editor']
};

console.log(newUser);
// Expected output: { id: '...', name: 'Jane Doe', email: 'jane.doe@example.com', age: 30, roles: [ 'editor' ] }

view raw JSON →