Registry / developer-tools / json-schema-to-jsdoc

json-schema-to-jsdoc

library1.1.1jsnpmunverified

Converts JSON Schema definitions into JSDoc @typedef and @property annotations. Version 1.1.1 stable, with low release cadence. Supports options like autoDescribe, hyphenatedDescriptions, custom types, and format mappings. Useful for generating type documentation from existing JSON schemas, particularly for object validation schemas.

developer-tools

npm install json-schema-to-jsdoc

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JSON-SCHEMA-TO-JSD

json-schema-to-jsdoc

developer-toolsjavascriptv1.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

jsdoc

✓ import jsdoc from 'json-schema-to-jsdoc'

✗ const jsdoc = require('json-schema-to-jsdoc')

Package is ESM-only since v1.0.0. Use import statement; require() will fail.

default

✓ import jsdoc from 'json-schema-to-jsdoc'

✗ import { jsonSchemaToJsdoc } from 'json-schema-to-jsdoc'

Default export only; no named exports.

type imports

✓ import type { Options } from 'json-schema-to-jsdoc'

TypeScript types are available; can be imported via type-only import.

Converts a simple JSON schema object into a JSDoc typedef with optional hyphenated property descriptions.

import jsdoc from 'json-schema-to-jsdoc'; const schema = { title: 'Person', type: 'object', properties: { name: { type: 'string', description: "A person's name" }, age: { type: 'integer', description: "A person's age" } }, required: ['name'] }; const result = jsdoc(schema, { hyphenatedDescriptions: true }); console.log(result); // Output: // /** // * @typedef {object} Person // * @property {string} name - A person's name // * @property {integer} [age] - A person's age // */

Debug

Known issues

breakingPackage is ESM-only; requires Node.js >= 16 and cannot be required() with CommonJS.

fix

Use dynamic import() if needed in CJS projects, or switch to ES modules.

affects: >=1.0.0

deprecatedThe 'addDescriptionLineBreak' option has been deprecated and may be removed in a future version.

fix

Use the 'descriptionPlaceholder' option instead, or omit to use default behavior.

affects: >=1.0.0

gotchaSchema properties without a 'type' will default to '*' type, which may not be desired. Use 'defaultPropertyType' option to override.

fix

Set 'defaultPropertyType' to a custom type like 'any' or null to omit type entirely.

affects: >=0.1.0

gotchaThe 'autoDescribe' option uses 'Represents a' for singular types; may produce awkward grammar for non-object types.

fix

Manually provide a 'description' in the schema to avoid auto-generated text.

affects: >=0.1.0

gotchaNested schemas with $ref are not resolved; only inline definitions are processed.

fix

Use a JSON Schema resolver like 'json-schema-ref-parser' to dereference before passing to this package.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: jsdoc is not a function

Using require() in CommonJS context; this is an ES module and does not export a CommonJS function.

fix

Replace require('json-schema-to-jsdoc') with import jsdoc from 'json-schema-to-jsdoc' or use dynamic import()

SyntaxError: Unexpected token 'export'

Package source contains ES module syntax; not transpiled for CJS environments.

fix

Ensure your project uses ES modules by setting 'type': 'module' in package.json, or use a bundler.

Error: Cannot find module 'json-schema-to-jsdoc'

Package not installed or Node.js version < 16 where ESM support is incomplete.

fix

Run npm install json-schema-to-jsdoc and ensure Node.js version >= 16.

Unexpected property 'formats' in options

The 'formats' option expects an object with specific structure; incorrect nesting or missing fields.

fix

Provide formats as { formatName: { type: 'customType' } } exactly as documented.

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

38 hits · last 30 days

node

Resources

githubhttps://github.com/n3ps/json-schema-to-jsdoc ↗

packagejson-schema-to-jsdoc ↗

homepagehttps://github.com/n3ps/json-schema-to-jsdoc ↗