Registry / serialization / json-schema-to-ts

json-schema-to-ts

library3.1.1jsnpmunverified

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.

serialization

npm install json-schema-to-ts

github ↗package ↗

INSTALL

IMPORT

SIG · JSON-SCHEMA-TO-TS

json-schema-to-ts

serializationjavascriptv3.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FromSchema

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

✗ 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

✓ import { asConst } from 'json-schema-to-ts'

✗ const schema = asConst({...})

asConst is a runtime utility function to help TypeScript infer a 'const' type for schemas, an alternative to the `as const` assertion.

JSONSchema

✓ import type { JSONSchema } from 'json-schema-to-ts'

✗ import { 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.

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' ] }

Debug

Known issues

breakingIn 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.

affects: >=3.0.0

gotchaForgetting 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.

affects: >=1.0.0

gotchaThe `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.

affects: <4.9

Errors

Common errors & fixes

Argument of type '{ type: string; properties: { name: { type: string; }; }; required: string[]; }' is not assignable to parameter of type 'JSONSchema'.

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.

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.

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.

Upgrade

Version history

3.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/ThomasAribart/json-schema-to-ts ↗

packagehttps://www.npmjs.com/package/json-schema-to-ts ↗