{"id":13698445,"url":"https://github.com/brettz9/jsdoc-jsonschema","last_synced_at":"2025-09-27T20:31:05.756Z","repository":{"id":57284256,"uuid":"265787472","full_name":"brettz9/jsdoc-jsonschema","owner":"brettz9","description":"Convert standard JSDoc @typedef comment blocks into JSON Schema (with support for nonstandard expansions).","archived":false,"fork":false,"pushed_at":"2023-04-23T12:40:29.000Z","size":277,"stargazers_count":6,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-08T18:57:43.879Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brettz9.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE-MIT.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-21T07:47:53.000Z","updated_at":"2024-11-15T20:08:14.000Z","dependencies_parsed_at":"2024-08-02T19:01:36.272Z","dependency_job_id":null,"html_url":"https://github.com/brettz9/jsdoc-jsonschema","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettz9%2Fjsdoc-jsonschema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettz9%2Fjsdoc-jsonschema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettz9%2Fjsdoc-jsonschema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettz9%2Fjsdoc-jsonschema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brettz9","download_url":"https://codeload.github.com/brettz9/jsdoc-jsonschema/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234455947,"owners_count":18835665,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T19:00:46.638Z","updated_at":"2025-09-27T20:31:00.375Z","avatar_url":"https://github.com/brettz9.png","language":"JavaScript","funding_links":["https://issuehunt.io/r/brettz9/jsdoc-jsonschema"],"categories":["Schema usage"],"sub_categories":["Type parsing"],"readme":"[![npm](https://img.shields.io/npm/v/jsdoc-jsonschema.svg)](https://www.npmjs.com/package/jsdoc-jsonschema)\n[![Dependencies](https://img.shields.io/david/brettz9/jsdoc-jsonschema.svg)](https://david-dm.org/brettz9/jsdoc-jsonschema)\n[![devDependencies](https://img.shields.io/david/dev/brettz9/jsdoc-jsonschema.svg)](https://david-dm.org/brettz9/jsdoc-jsonschema?type=dev)\n\n\u003c!--[![Actions Status](https://github.com/brettz9/jsdoc-jsonschema/workflows/Node%20CI/badge.svg)](https://github.com/brettz9/jsdoc-jsonschema/actions)--\u003e\n[![Build Status](https://travis-ci.org/n3ps/json-schema-to-jsdoc.svg?branch=master)](https://travis-ci.org/n3ps/json-schema-to-jsdoc)\n[![testing badge](https://raw.githubusercontent.com/brettz9/jsdoc-jsonschema/master/badges/tests-badge.svg?sanitize=true)](badges/tests-badge.svg)\n[![coverage badge](https://raw.githubusercontent.com/brettz9/jsdoc-jsonschema/master/badges/coverage-badge.svg?sanitize=true)](badges/coverage-badge.svg)\n\u003c!--\n[![Actions Status](https://github.com/brettz9/jsdoc-jsonschema/workflows/Coverage/badge.svg)](https://github.com/brettz9/jsdoc-jsonschema/actions)\n--\u003e\n\n[![Known Vulnerabilities](https://snyk.io/test/github/brettz9/jsdoc-jsonschema/badge.svg)](https://snyk.io/test/github/brettz9/jsdoc-jsonschema)\n[![Total Alerts](https://img.shields.io/lgtm/alerts/g/brettz9/jsdoc-jsonschema.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/brettz9/jsdoc-jsonschema/alerts)\n[![Code Quality: Javascript](https://img.shields.io/lgtm/grade/javascript/g/brettz9/jsdoc-jsonschema.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/brettz9/jsdoc-jsonschema/context:javascript)\n\n\u003c!--[![License](https://img.shields.io/npm/l/jsdoc-jsonschema.svg)](LICENSE-MIT.txt)--\u003e\n[![Licenses badge](https://raw.githubusercontent.com/brettz9/jsdoc-jsonschema/master/badges/licenses-badge.svg?sanitize=true)](badges/licenses-badge.svg)\n\n(see also [licenses for dev. deps.](https://raw.githubusercontent.com/brettz9/jsdoc-jsonschema/master/badges/licenses-badge-dev.svg?sanitize=true))\n\n[![issuehunt-to-marktext](https://issuehunt.io/static/embed/issuehunt-button-v1.svg)](https://issuehunt.io/r/brettz9/jsdoc-jsonschema)\n\n# jsdoc-jsonschema\n\nConvert standard JSDoc `@typedef` comment blocks into JSON Schema (with\nsupport for nonstandard expansions).\n\n## Use cases\n\n- Validating the arguments passed to one's code at run-time\n- For command-line scripts, one may need to apply schemas to the strings\n    passed in in order to get typed info back out.\n\nJSDoc is needed within code for good API docs anyways (one could build them\nfrom JSON Schema, but then they wouldn't be integrated into one's code),\nbut since the information is redundant with JSON Schema, it can save time\nfrom having to build both.\n\n## Current features\n\n| JSDoc | JSON Schema | Notes |\n|-------|-------------|-------|\n| `@typedef` | `{type: 'object'}` |\n| `/** Some desc.\\n\\n* @typedef */` | `{type: 'object', description: 'Some desc.'}` |\n| `@typedef typeName` | `{type: 'object', title: 'typeName'}` |\n| `@property {integer} propName` | `{properties: {propName: {type: 'integer'}}, required: ['propName']}`\n| `@property {3\\|4\\|5} propName` | `{properties: {propName: {type: 'number', enum: [3, 4, 5]}}, required: ['propName']}` | Can force to `integer` type\n| `@typedef {3\\|4\\|5}` | `{type: 'number', enum: [3, 4, 5]}` | Can force to `integer` type\n| `@typedef {SomeType \u0026 (AnotherType \\| YetAnotherType)}` | `{allOf: [{classRelation: 'is-a', $ref: '$defs/SomeType'}, {anyOf: [{classRelation: 'is-a', $ref: '$defs/AnotherType'}, {classRelation: 'is-a', $ref: '$defs/YetAnotherType'}]}]}` | Inner parenthesized unions and/or intersections\n| `@property {integer} [propName] Prop desc.` | `{properties: {propName: {type: 'integer', description: 'Prop desc.'}}}` | Supported JSON Schema types: 'null', 'boolean', 'object', 'array', 'number', 'string', 'integer'; with `tolerateCase` option not disabled, will allow `Integer`, etc., as well\n| `@property {string[]} [propName] Prop. desc.` | `{properties: {propName: {type: 'array', description: 'Prop desc.', items: {type: 'string'}}}}`\n| `@property {string[]|number[]} [propName] Prop. desc.` | `{properties: {propName: {type: 'array', description: 'Prop desc.', items: {anyOf: [{type: 'string'}, {type: 'number'}]}}}}`\n\n## FAQ\n\n### Why not just use JSON Schema?\n\nWhile JSON Schema is nicely structured for consumption by JavaScript,\nit is not integrated within one's code.\n\nAnd when the schema is discoverable within one's code in the context where\nit is defined and maintained, one is surely more likely to keep it up to date.\n\n### Won't you become unable to express certain JSON Schema features coming from JSDoc?\n\nJSDoc already has certain standard tags that can express certain JSON schema\nfeatures like `type` and `properties`. We want to leverage those standard\nfeatures where they exist.\n\nHowever, JSDoc can support definition of custom tags, so if necessary, we\ncan add certain features that can be converted into other JSON Schema features.\n\n## Installation\n\n```sh\nnpm i jsdoc-jsonschema\n```\n\n## Usage\n\n```js\nimport {jsdocToJsonSchema} from 'jsdoc-jsonschema';\n\njsdocToJsonSchema(`\n  /**\n   * @typedef {PlainObject} ParentType\n   * @property {number} numName\n   */\n`);\n```\n\n```json\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"numName\": {\n      \"type\": \"number\"\n    }\n  }\n}\n```\n\n### Options\n\nAs a second argument, one can supply an options object with the following\nproperties:\n\n- `$defs` - Boolean (default `false`) on whether to produce a schema with\n    `$defs`. Expected when seeking to build `is-a` structures (with a single\n    root).\n- `preferInteger` - Boolean (default `false`) on whether to prefer `integer`\n    as a schema `type` when the number has no decimal value.\n- `tolerateCase` - Boolean (default `true`) on whether to allow types defined\n    in different casing, e.g., `Object`, to avoid throwing and be converted to\n    their lower-case counterpart understood by JSON Schema.\n- `throwOnUnrecognizedName` - Boolean (default `true`) on whether to throw\n    upon encountering a type that is not a JSON-schema type (unless a custom\n    type is supplied).\n- `types` - Object (defaults to `{PlainObject: {type: 'object'}}`) whose keys\n    are custom type names and whose values are objects with `type` and/or\n    `format`. If one of the custom types is found in a jsdoc type, its\n    conversion to JSON Schema will result in the object's `type` and/or\n    `format`.\n\n## CLI\n\n![badges/cli.svg](./badges/cli.svg)\n\n## Scope\n\nThis project does not aim to convert other similar sources such as TypeScript\ndefinition files (though see the links below for that).\n\nHowever, it is, for now, using [`jsdoctypeparser`](https://github.com/jsdoctypeparser/jsdoctypeparser/)\n(over the standard jsdoc [catharsis](https://github.com/hegemonic/catharsis))\nso that, in theory, we could allow conversion of TypeScript-specific types\nwithin jsdoc comments into suitable schema features (e.g., intersections).\n\n## See also\n\n- Converting from JSON Schema to jsdoc:\n    [json-schema-to-jsdoc](https://github.com/n3ps/json-schema-to-jsdoc).\n- jsdoc to Typescript:\n    - [typescript-json-schema](https://github.com/YousefED/typescript-json-schema)\n    - [ts-json-schema-generator](https://github.com/vega/ts-json-schema-generator)\n- TypeScript to jsdoc:\n    [json-schema-to-typescript](https://github.com/bcherny/json-schema-to-typescript)\n- Linting your JSDoc comments:\n    [eslint-plugin-jsdoc](https://github.com/gajus/eslint-plugin-jsdoc)\n\n## To-dos\n\n1. Switch from `jsdoctypeparser` to `jsdoc-type-pratt-parser`\n1. Get binary to support saving separate typedefs within a file to\n    different output files\n1. Add whitelist option so only get desired typedef and its parents out of\n    a file (may be useful with `command-line-basics`).\n1. Add support in `json-schema-to-jsdoc`\n    ([#41](https://github.com/n3ps/json-schema-to-jsdoc/issues/41))\n    for `@typedef`'s referencing other `@typedef`'s to complete commented\n    out sanity checks in tests; resume using stable version once may be merged\n\n## Lower-priority to-dos\n\n1. Support **file globs** and output directory\n1. Get working with **mixed union types** (and for TS, **intersection types**)\n1. Add **mixed literals as `enum`** with `type` array\n1. **Nested types**, e.g., nullable\n1. Use `title` with `@property` despite being redundant with `properties` key?\n1. Convert TS negated type to **`not`**?\n1. Option to **read from file**, optionally filtering out only the `@typedef`'s\n    of interest (by whitelist and/or blacklist)\n1. Option to **save to file** (based on `@typedef` tag name and/or other\n    custom tags?)\n1. Add method to support **parsing entire `import`/`require` pipeline** for\n    `@typedef`'s for conversion to schemas (could use\n    [es-file-traverse](https://github.com/brettz9/es-file-traverse))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrettz9%2Fjsdoc-jsonschema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrettz9%2Fjsdoc-jsonschema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrettz9%2Fjsdoc-jsonschema/lists"}