Generate JSON schemas from JavaScript code comments using a new jsDoc @schema tag.
npm install --save jsdoc-to-json-schema
var toJsonSchema = require('jsdoc-to-json-schema'); // OPTION 1: generate a JSON schema for product.js and save it to disk toJsonSchema('./example/product.js', './example/product.schema.json'); // OPTION 2: generate a JSON schema and return it as an object toJsonSchema('./example/product.js').then(function(schema){ // do something with it }); // OPTION 3: generate a JSON schema, save it to disk and return it as an object toJsonSchema('./example/product.js', './example/product.schema.json').then(function(schema){ // do something with it });
# install the module globally $ npm install -g jsdoc-to-json-schema # execute from command line passing input and output paths $ jsdoc-to-json-schema -i ./example/product.js -o ./example/product.schema.json
var express = require('express'); var app = express(); var toJsonSchema = require('../lib/jsdoc-to-json-schema.js'); // create an express route app.get('/', function(req, res){ // pipe schema directly to the response stream toJsonSchema('./examples/person.js', res); }); // start the server listening on port 8080 app.listen(8080, function(){ console.log('Example app listening on port 8080'); });
For use with express consider the dedicated express middleware project express-json-schema
JavaScript file containing jsDoc @schema tags used to define the JSON schema:
/** * @schema.name Person * @schema.description This is an example Person object marked up with JSON schema tags to allow schema generation */ var Person = { /** * @schema.title Name * @schema.description Please enter your full name * @schema.type string * @schema.maxLength 30 * @schema.minLength 1 * @schema.required true */ name: '', /** * @schema.title Job Title * @schema.type string */ jobTitle: '', /** * @schema.title Telephone Number * @schema.description Please enter telephone number including country code * @schema.type string * @schema.required true */ telephone: '', /** * @schema.type string * @schema.required true */ dateOfBirth: '' };
{ "name": "Person", "description": "This is an example Person object marked up with JSON schema tags to allow schema generation", "properties": { "name": { "title": "Name", "description": "Please enter your full name", "type": "string", "maxLength": 30, "minLength": 1, "required": true }, "jobTitle": { "title": "Job Title", "type": "string" }, "telephone": { "title": "Telephone Number", "description": "Please enter telephone number including country code", "type": "string", "required": true }, "dateOfBirth": { "type": "string", "required": true }, "address": { "type": "object" } } }
JavaScript file containing jsDoc @schema tags used to define the JSON schema:
/** * @schema.name Product * @schema.description An example product marked up with json schema comments */ function Product(){ } /** * @schema.type array * @schema.minItems 3 * @schema.maxItems 6 * @schema.required true */ Product.prototype.types = function(){ }
{ "name": "Product", "description": "An example product marked up with json schema comments", "properties": { "types": { "type": "array", "minItems": 3, "maxItems": 6, "required": true } } }
The following JSON Schema v3 tags are supported, however undocumented @schema tags will also be generated in order to aid extensibility.
Note: @schema tags without an associated value will be ignored.
Tag | Type |
---|---|
@schema.name | string |
@schema.description | string |
@schema.extends | string |
@schema.id | string |
@schema.type | string |
@schema.pattern | string |
@schema.title | string |
@schema.format | string |
@schema.disallow | string |
@schema.enum | array |
@schema.minimum | integer |
@schema.maximum | integer |
@schema.minItems | integer |
@schema.maxItems | integer |
@schema.minLength | integer |
@schema.maxLength | integer |
@schema.exclusiveMinimum | integer |
@schema.exclusiveMaximum | integer |
@schema.divisibleBy | integer |
@schema.required | boolean |
@schema.uniqueItems | boolean |
@schema.default | any |
Install dev dependencies and run tests:
$ npm install -d && npm test
Licensed under ISC License © John Doherty