json-schema-to-typescript is a utility that compiles JSON Schemas into TypeScript type declarations, enabling strong typing for data structures defined in JSON. Currently at version 15.0.4, it offers both a command-line interface (CLI) for file-based conversions and a programmatic API for integrating into build processes or applications. It is actively maintained with regular updates. Key differentiators include its robust handling of various JSON Schema features like `allOf`, `anyOf`, `oneOf`, `definitions`, and `$ref` for both local and external references. It aims to provide a reliable way to keep TypeScript types synchronized with JSON Schema definitions, reducing manual type creation and potential discrepancies between data contracts and application code. The library supports customizable options for output formatting, banner comments, and how `additionalProperties` are handled, which is crucial for controlling the strictness of generated types. It's particularly useful for projects consuming APIs or data where JSON Schema is the source of truth, facilitating a 'schema-first' development approach.
npm install json-schema-to-typescriptVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to programmatically compile a JSON Schema to TypeScript types, both from an in-memory object and from a file, using common configuration options. It creates a temporary `schema.json` and outputs `types.d.ts`.
Always explicitly define `additionalProperties` in your JSON Schema (`true`, `false`, or a sub-schema) or pass `{ additionalProperties: false }` (or `true`) in the `Options` object to `compile` or `compileFromFile` to ensure consistent behavior. For CLI, use `--no-additionalProperties` or `--additionalProperties`.Carefully review schemas using `oneOf`/`anyOf`/`allOf`. Ensure they are unambiguous and provide clear type inference paths. Consider using `discriminator` if applicable for `oneOf` to guide type inference. If `unknown` types appear, simplify the schema or add `tsType` annotations (custom schema properties) as a workaround.
For large schemas, set `format: false` in the options object (`{ format: false }`) to disable internal Prettier formatting, then apply formatting manually if needed. For CLI, use `--no-format`.Always refer to the documentation for your specific installed version. For the main `json-schema-to-typescript` package, upgrading to the latest stable version (currently 15.x) is recommended for the most current features and fixes.
When using `json-schema-to-typescript` in a browser environment, use the `compile` function with an in-memory JSON Schema object. You will need to fetch the schema content separately if it resides on a server.
Verify that the path to your JSON Schema file is correct and that the file has appropriate read permissions. Ensure relative paths are resolved correctly, e.g., using `path.join(__dirname, 'your-schema.json')`.
Ensure your project is configured for ES modules (e.g., `"type": "module"` in `package.json`) and that you are using `import { compile } from 'json-schema-to-typescript'` syntax. If running directly in Node.js, confirm your file uses `.mjs` extension or `type: module`.Refactor your imports to use ES module `import` syntax: `import { compile, compileFromFile } from 'json-schema-to-typescript'`. If you need conditional imports, consider dynamic `import()`.Set `"additionalProperties": false` in your JSON Schema to disallow undeclared properties, or pass `{ additionalProperties: false }` to the `compile` options. Alternatively, if `additionalProperties` is desired, ensure all explicitly defined properties are not `undefined` or handle them appropriately.No dependency data recorded yet.