JSDOC - Schema for validating JSDoc doclets

jsdoc-schema.js

/**
 * Schema for validating JSDoc doclets.
 * @module jsdoc/schema
 * @see <https://trac.tools.ietf.org/html/draft-wright-json-schema-validation-01>
 */
// JSON schema types
const ARRAY = 'array';
const BOOLEAN = 'boolean';
const NULL = 'null';
const NUMBER = 'number';
const OBJECT = 'object';
const STRING = 'string';

const BOOLEAN_OPTIONAL = [BOOLEAN, NULL];
const STRING_OPTIONAL = [STRING, NULL];

const EVENT_REGEXP = 'event:[\\S]+';
const PACKAGE_REGEXP = 'package:[\\S]+';

const STRING_SCHEMA = {
    type: STRING
};

// information about the code associated with a doclet
const META_SCHEMA = exports.META_SCHEMA = {
    type: OBJECT,
    additionalProperties: false,
    properties: {
        code: {
            type: OBJECT,
            additionalProperties: false,
            properties: {
                funcscope: {
                    type: STRING
                },
                id: {
                    type: STRING
                },
                name: {},
                node: {
                    type: OBJECT
                },
                paramnames: {
                    type: ARRAY,
                    uniqueItems: true,
                    items: {
                        type: STRING
                    }
                },
                type: {
                    type: STRING
                },
                value: {}
            }
        },
        columnno: {
            title: 'The column number of the code associated with this doclet.',
            type: NUMBER
        },
        filename: {
            title: 'The name of the file that contains the code associated with this doclet.',
            type: STRING
        },
        lineno: {
            title: 'The line number of the code associated with this doclet.',
            type: NUMBER
        },
        path: {
            title: 'The path in which the code associated with this doclet is located.',
            type: STRING
        },
        range: {
            title: 'The positions of the first and last characters of the code associated with ' +
                'this doclet.',
            type: ARRAY,
            minItems: 2,
            maxItems: 2,
            items: {
                type: NUMBER
            }
        },
        vars: {
            type: OBJECT
        }
    }
};

// type property containing type names
const TYPE_PROPERTY_SCHEMA = exports.TYPE_PROPERTY_SCHEMA = {
    type: OBJECT,
    additionalProperties: false,
    properties: {
        names: {
            type: ARRAY,
            minItems: 1,
            items: {
                type: STRING
            }
        },
        // type parser output
        parsedType: {
            type: OBJECT,
            additionalProperties: true
        }
    }
};

// enumeration properties
const ENUM_PROPERTY_SCHEMA = exports.ENUM_PROPERTY_SCHEMA = {
    type: OBJECT,
    additionalProperties: false,
    properties: {
        comment: {
            type: STRING
        },
        defaultvalue: {},
        description: {
            type: STRING_OPTIONAL
        },
        kind: {
            type: STRING,
            enum: ['member']
        },
        longname: {
            type: STRING
        },
        memberof: {
            type: STRING
        },
        meta: META_SCHEMA,
        name: {
            type: STRING
        },
        // is this member nullable? (derived from the type expression)
        nullable: {
            type: BOOLEAN_OPTIONAL
        },
        // is this member optional? (derived from the type expression)
        optional: {
            type: BOOLEAN_OPTIONAL
        },
        scope: {
            type: STRING,
            enum: ['static']
        },
        type: TYPE_PROPERTY_SCHEMA,
        // can this member be provided more than once? (derived from the type expression)
        variable: {
            type: BOOLEAN_OPTIONAL
        }
    }
};

// function parameter, or object property defined with @property tag
const PARAM_SCHEMA = exports.PARAM_SCHEMA = {
    type: OBJECT,
    additionalProperties: false,
    properties: {
        // what is the default value for this parameter?
        defaultvalue: {},
        // a description of the parameter
        description: {
            type: STRING_OPTIONAL
        },
        // what name does this parameter have within the function?
        name: {
            type: STRING
        },
        // can the value for this parameter be null?
        nullable: {
            type: BOOLEAN_OPTIONAL
        },
        // is a value for this parameter optional?
        optional: {
            type: BOOLEAN_OPTIONAL
        },
        // what are the types of value expected for this parameter?
        type: TYPE_PROPERTY_SCHEMA,
        // can this parameter be repeated?
        variable: {
            type: BOOLEAN_OPTIONAL
        }
    }
};

const DOCLET_SCHEMA = exports.DOCLET_SCHEMA = {
    type: OBJECT,
    additionalProperties: false,
    properties: {
        // what access privileges are allowed
        access: {
            type: STRING,
            enum: [
                'package',
                'private',
                'protected',
                'public'
            ]
        },
        alias: {
            type: STRING
        },
        async: {
            type: BOOLEAN
        },
        augments: {
            type: ARRAY,
            uniqueItems: true,
            items: {
                type: STRING
            }
        },
        author: {
            type: ARRAY,
            items: {
                type: STRING
            }
        },
        borrowed: {
            type: ARRAY,
            uniqueItems: true,
            items: {
                type: OBJECT,
                additionalProperties: false,
                properties: {
                    // name of the target
                    as: {
                        type: STRING
                    },
                    // name of the source
                    from: {
                        type: STRING
                    }
                }
            }
        },
        // a description of the class that this constructor belongs to
        classdesc: {
            type: STRING
        },
        comment: {
            type: STRING
        },
        copyright: {
            type: STRING
        },
        defaultvalue: {},
        defaultvaluetype: {
            type: STRING,
            enum: [OBJECT, ARRAY]
        },
        // is usage of this symbol deprecated?
        deprecated: {
            type: [STRING, BOOLEAN]
        },
        // a description
        description: {
            type: STRING_OPTIONAL
        },
        // something else to consider
        examples: {
            type: ARRAY,
            items: {
                type: STRING
            }
        },
        exceptions: {
            type: ARRAY,
            items: PARAM_SCHEMA
        },
        // the path to another constructor
        extends: {
            type: ARRAY,
            uniqueItems: true,
            items: {
                type: STRING
            }
        },
        // the path to another doc object
        fires: {
            type: ARRAY,
            uniqueItems: true,
            items: {
                type: STRING,
                pattern: EVENT_REGEXP
            }
        },
        forceMemberof: {
            type: BOOLEAN_OPTIONAL
        },
        generator: {
            type: BOOLEAN
        },
        hideconstructor: {
            type: BOOLEAN
        },
        ignore: {
            type: BOOLEAN
        },
        implementations: {
            type: ARRAY,
            items: {
                type: STRING
            }
        },
        implements: {
            type: ARRAY,
            items: {
                type: STRING
            }
        },
        inheritdoc: {
            type: STRING
        },
        inherited: {
            type: BOOLEAN
        },
        inherits: {
            type: STRING,
            dependency: {
                inherited: true
            }
        },
        isEnum: {
            type: BOOLEAN
        },
        // what kind of symbol is this?
        kind: {
            type: STRING,
            enum: [
                'class',
                'constant',
                'event',
                'external',
                'file',
                'function',
                'interface',
                'member',
                'mixin',
                'module',
                'namespace',
                'package',
                'param',
                'typedef'
            ]
        },
        license: {
            type: STRING
        },
        listens: {
            type: ARRAY,
            uniqueItems: true,
            items: {
                type: STRING,
                pattern: EVENT_REGEXP
            }
        },
        longname: {
            type: STRING
        },
        // probably a leading substring of the path
        memberof: {
            type: STRING
        },
        // information about this doc
        meta: META_SCHEMA,
        // was this doclet mixed in?
        mixed: {
            type: BOOLEAN
        },
        mixes: {
            type: ARRAY,
            uniqueItems: true,
            items: {
                type: STRING
            }
        },
        modifies: {
            type: ARRAY,
            uniqueItems: true,
            items: PARAM_SCHEMA
        },
        // probably a trailing substring of the path
        name: {
            type: STRING
        },
        // is this member nullable? (derived from the type expression)
        nullable: {
            type: BOOLEAN_OPTIONAL
        },
        // is this member optional? (derived from the type expression)
        optional: {
            type: BOOLEAN_OPTIONAL
        },
        // does this member explicitly override the parent?
        override: {
            type: BOOLEAN
        },
        overrides: {
            type: STRING
        },
        // are there function parameters associated with this doc?
        params: {
            type: ARRAY,
            uniqueItems: true,
            items: PARAM_SCHEMA
        },
        preserveName: {
            type: BOOLEAN
        },
        properties: {
            type: ARRAY,
            uniqueItems: true,
            minItems: 1,
            items: {
                anyOf: [ENUM_PROPERTY_SCHEMA, PARAM_SCHEMA]
            }
        },
        readonly: {
            type: BOOLEAN
        },
        // the symbol being documented requires another symbol
        requires: {
            type: ARRAY,
            uniqueItems: true,
            minItems: 1,
            items: {
                type: STRING
            }
        },
        returns: {
            type: ARRAY,
            minItems: 1,
            items: PARAM_SCHEMA
        },
        // what sort of parent scope does this symbol have?
        scope: {
            type: STRING,
            enum: [
                'global',
                'inner',
                'instance',
                'static'
            ]
        },
        // something else to consider
        see: {
            type: ARRAY,
            minItems: 1,
            items: {
                type: STRING
            }
        },
        // at what previous version was this doc added?
        since: {
            type: STRING
        },
        summary: {
            type: STRING
        },
        // arbitrary tags associated with this doc
        tags: {
            type: ARRAY,
            minItems: 1,
            items: {
                type: OBJECT,
                additionalProperties: false,
                properties: {
                    originalTitle: {
                        type: STRING
                    },
                    text: {
                        type: STRING
                    },
                    title: {
                        type: STRING
                    },
                    value: {
                        oneOf: [STRING_SCHEMA, PARAM_SCHEMA]
                    }
                }
            }
        },
        'this': {
            type: STRING
        },
        todo: {
            type: ARRAY,
            minItems: 1,
            items: {
                type: STRING
            }
        },
        // extended tutorials
        tutorials: {
            type: ARRAY,
            minItems: 1,
            items: {
                type: STRING
            }
        },
        // what type is the value that this doc is associated with, like `number`
        type: TYPE_PROPERTY_SCHEMA,
        undocumented: {
            type: BOOLEAN
        },
        // can this member be provided more than once? (derived from the type expression)
        variable: {
            type: BOOLEAN_OPTIONAL
        },
        variation: {
            type: STRING
        },
        // what is the version of this doc
        version: {
            type: STRING
        },
        // is a member left to be implemented during inheritance?
        virtual: {
            type: BOOLEAN
        },
        yields: {
            type: ARRAY,
            minItems: 1,
            items: PARAM_SCHEMA
        }
    }
};

const CONTACT_INFO_SCHEMA = exports.CONTACT_INFO_SCHEMA = {
    type: OBJECT,
    additionalProperties: false,
    properties: {
        email: {
            type: STRING
        },
        name: {
            type: STRING
        },
        url: {
            type: STRING,
            format: 'uri'
        }
    }
};

const BUGS_SCHEMA = exports.BUGS_SCHEMA = {
    type: OBJECT,
    additionalProperties: false,
    properties: {
        email: {
            type: STRING
        },
        url: {
            type: STRING,
            format: 'uri'
        }
    }
};

const PACKAGE_SCHEMA = exports.PACKAGE_SCHEMA = {
    type: OBJECT,
    additionalProperties: false,
    properties: {
        author: {
            anyOf: [STRING_SCHEMA, CONTACT_INFO_SCHEMA]
        },
        bugs: {
            anyOf: [STRING_SCHEMA, BUGS_SCHEMA]
        },
        contributors: {
            type: ARRAY,
            minItems: 0,
            items: {
                anyOf: [STRING_SCHEMA, CONTACT_INFO_SCHEMA]
            }
        },
        dependencies: {
            type: OBJECT
        },
        description: {
            type: STRING
        },
        devDependencies: {
            type: OBJECT
        },
        engines: {
            type: OBJECT
        },
        files: {
            type: ARRAY,
            uniqueItems: true,
            minItems: 0,
            items: {
                type: STRING
            }
        },
        homepage: {
            type: STRING,
            format: 'uri'
        },
        keywords: {
            type: ARRAY,
            minItems: 0,
            items: {
                type: STRING
            }
        },
        kind: {
            type: STRING,
            enum: ['package']
        },
        licenses: {
            type: ARRAY,
            minItems: 1,
            items: {
                type: OBJECT,
                additionalProperties: false,
                properties: {
                    type: {
                        type: STRING
                    },
                    url: {
                        type: STRING,
                        format: 'uri'
                    }
                }
            }
        },
        longname: {
            type: STRING,
            pattern: PACKAGE_REGEXP
        },
        main: {
            type: STRING
        },
        name: {
            type: STRING
        },
        repository: {
            type: OBJECT,
            additionalProperties: false,
            properties: {
                type: {
                    type: STRING
                },
                // we don't use `format: 'uri'` here because repo URLs are atypical
                url: {
                    type: STRING
                }
            }
        },
        version: {
            type: STRING
        }
    }
};

exports.DOCLETS_SCHEMA = {
    type: ARRAY,
    items: {
        anyOf: [DOCLET_SCHEMA, PACKAGE_SCHEMA]
    }
};