Convert standard JSDoc @typedef comment blocks into JSON Schema (with support for nonstandard expansions).
MIT License
(see also licenses for dev. deps.)
Convert standard JSDoc @typedef
comment blocks into JSON Schema (with
support for nonstandard expansions).
JSDoc is needed within code for good API docs anyways (one could build them from JSON Schema, but then they wouldn't be integrated into one's code), but since the information is redundant with JSON Schema, it can save time from having to build both.
JSDoc | JSON Schema | Notes |
---|---|---|
@typedef |
{type: 'object'} |
|
/** Some desc.\n\n* @typedef */ |
{type: 'object', description: 'Some desc.'} |
|
@typedef typeName |
{type: 'object', title: 'typeName'} |
|
@property {integer} propName |
{properties: {propName: {type: 'integer'}}, required: ['propName']} |
|
@property {3|4|5} propName |
{properties: {propName: {type: 'number', enum: [3, 4, 5]}}, required: ['propName']} |
Can force to integer type |
@typedef {3|4|5} |
{type: 'number', enum: [3, 4, 5]} |
Can force to integer type |
@typedef {SomeType & (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 |
@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 |
@property {string[]} [propName] Prop. desc. |
{properties: {propName: {type: 'array', description: 'Prop desc.', items: {type: 'string'}}}} |
|
`@property {string[] | number[]} [propName] Prop. desc.` | {properties: {propName: {type: 'array', description: 'Prop desc.', items: {anyOf: [{type: 'string'}, {type: 'number'}]}}}} |
While JSON Schema is nicely structured for consumption by JavaScript, it is not integrated within one's code.
And when the schema is discoverable within one's code in the context where it is defined and maintained, one is surely more likely to keep it up to date.
JSDoc already has certain standard tags that can express certain JSON schema
features like type
and properties
. We want to leverage those standard
features where they exist.
However, JSDoc can support definition of custom tags, so if necessary, we can add certain features that can be converted into other JSON Schema features.
npm i jsdoc-jsonschema
import {jsdocToJsonSchema} from 'jsdoc-jsonschema';
jsdocToJsonSchema(`
/**
* @typedef {PlainObject} ParentType
* @property {number} numName
*/
`);
{
"type": "object",
"properties": {
"numName": {
"type": "number"
}
}
}
As a second argument, one can supply an options object with the following properties:
$defs
- Boolean (default false
) on whether to produce a schema with$defs
. Expected when seeking to build is-a
structures (with a singlepreferInteger
- Boolean (default false
) on whether to prefer integer
type
when the number has no decimal value.tolerateCase
- Boolean (default true
) on whether to allow types definedObject
, to avoid throwing and be converted tothrowOnUnrecognizedName
- Boolean (default true
) on whether to throwtypes
- Object (defaults to {PlainObject: {type: 'object'}}
) whose keystype
and/orformat
. If one of the custom types is found in a jsdoc type, itstype
and/orformat
.This project does not aim to convert other similar sources such as TypeScript definition files (though see the links below for that).
However, it is, for now, using jsdoctypeparser
(over the standard jsdoc catharsis)
so that, in theory, we could allow conversion of TypeScript-specific types
within jsdoc comments into suitable schema features (e.g., intersections).
jsdoctypeparser
to jsdoc-type-pratt-parser
command-line-basics
).json-schema-to-jsdoc
@typedef
's referencing other @typedef
's to complete commentedenum
with type
arraytitle
with @property
despite being redundant with properties
key?not
?@typedef
's@typedef
tag name and/or otherimport
/require
pipeline for@typedef
's for conversion to schemas (could use