Registry / serialization / schema-typescript

schema-typescript

library0.14.3jsnpmunverified

This package facilitates the automatic conversion of JSON Schema definitions into TypeScript interfaces and types. It is currently at version 0.14.3 and appears to be actively maintained, with its last publish occurring four days ago as of the current date, indicating a relatively frequent release cadence. A key differentiator is its robust handling of standard JSON Schema features like `$ref` and `$defs` for modular schema definitions, and its ability to process arrays of defined types seamlessly into TypeScript arrays. Unlike some alternative tools that focus on generating JSON Schema *from* TypeScript code, this library specifically targets the generation of TypeScript *from* existing JSON Schema, providing a critical tool for schema-first development workflows. It operates with minimal dependencies and is part of the broader `constructive-io/dev-utils` monorepo, although it is designed for general-purpose use.

serialization

npm install schema-typescript

github ↗package ↗

INSTALL

IMPORT

SIG · SCHEMA-TYPESCRIPT

schema-typescript

serializationjavascriptv0.14.3

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.

generateTypeScript

✓ import { generateTypeScript } from 'schema-typescript';

✗ const generateTypeScript = require('schema-typescript');

The library primarily uses named exports. Direct CommonJS `require` might lead to `undefined` or a `TypeError` if not properly transpiled or if `esModuleInterop` is not configured, as it is designed for ESM environments.

This quickstart demonstrates how to import the `generateTypeScript` function and convert a sample JSON Schema object for a 'User' into a TypeScript interface string, then write it to a file.

import { generateTypeScript } from 'schema-typescript'; import * as fs from 'node:fs/promises'; const userSchema = { "$id": "https://example.com/user.schema.json", "$schema": "http://json-schema.org/draft-07/schema#", "title": "User", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Full name of the user" }, "email": { "type": "string", "format": "email" }, "age": { "type": "integer", "minimum": 0, "maximum": 150 }, "isActive": { "type": "boolean", "default": true } }, "required": ["id", "name", "email"] }; async function generateUserTypes() { try { const tsDefinition = await generateTypeScript(userSchema, 'User'); await fs.writeFile('src/types/user.d.ts', tsDefinition); console.log('TypeScript types for User generated successfully to src/types/user.d.ts'); console.log('\nGenerated TypeScript:\n', tsDefinition); } catch (error) { console.error('Failed to generate TypeScript types:', error); } } generateUserTypes();

Debug

Known issues

gotchaThe package is currently in a pre-1.0 version (0.14.3). While actively maintained, this implies that breaking changes could occur in minor versions, not just major ones, unlike libraries adhering to strict semver after 1.0. Review release notes carefully during upgrades.

fix

Always pin to exact patch versions (`~0.14.3` instead of `^0.14.3`) in `package.json` and consult release notes before upgrading to a new minor version.

affects: >=0.1.0

gotchaComplex or highly customized JSON Schema features, especially intricate `$ref` resolution across multiple files or non-standard keywords, might not be fully supported or could lead to unexpected TypeScript output.

fix

Test the conversion with representative complex schemas. For critical or edge-case schemas, consider simplifying the JSON Schema or manually adjusting the generated TypeScript definitions. Report specific issues to the maintainers.

affects: >=0.1.0

gotchaAs part of the `constructive-io/dev-utils` monorepo, while functional as a standalone utility, there might be implicit assumptions or optimizations tailored for the broader `constructive-io` ecosystem. This generally does not affect direct usage, but advanced users integrating deeply might encounter subtle interactions.

fix

Refer to the GitHub repository for `constructive-io/dev-utils` for the latest context and any ecosystem-specific guidelines if encountering unexpected behavior in complex integrations.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: generateTypeScript is not a function

Attempting to import `generateTypeScript` using CommonJS `require()` syntax in an environment that expects ESM, or incorrect named/default export handling.

fix

Ensure you are using `import { generateTypeScript } from 'schema-typescript';` in an ESM-compatible environment (e.g., Node.js with `"type": "module"` in `package.json` or a bundler configured for ESM).

Error: Invalid JSON Schema structure encountered

The input object passed to `generateTypeScript` is not a valid JSON Schema object, missing required properties, or contains syntax errors.

fix

Validate your JSON Schema against the JSON Schema specification (e.g., using `ajv` or an online validator) before passing it to the function. Ensure all required fields like `type` are present and correctly formatted.

ReferenceError: Could not resolve schema reference '#/definitions/MyType'

The JSON Schema contains a `$ref` that points to a definition (`#/definitions/MyType` or an external file) that either does not exist, is misspelled, or cannot be accessed/resolved by the library's internal resolver.

fix

Verify that all `$ref` pointers are correct and that the referenced schemas are accessible. For external `$ref`s, ensure they are correctly provided to the library if it supports such options, or pre-resolve them if necessary.

Upgrade

Version history

0.14.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/constructive-io/dev-utils ↗

packagehttps://www.npmjs.com/package/schema-typescript ↗