sequelize-json-schema

Generate JSON Schema structures from Sequelize instances, models, and model attributes.

Schemas may be generated at three levels of granularity:


`getSequelizeSchema()`	Generate a full description of your database (all models, attributes, and associations)
`getModelSchema()`	Generate the schema `definitions` entry for a specific model (all attributes)
`getAttributeSchema()`	Generate the `properties` entry for a specific attribute

See API documentation below for details and examples.

Installation

npm install sequelize-json-schema

Migrating v1 → v2

The version 1 API of this module is available as getModelSchema(), with the following changes:

private option has been removed. Use exclude instead.
alwaysRequired option has been removed. Schemas should be manually amended if needed using schema.required.push(...Object.keys(schema.properties)).
allowNull option has been removed. (Schema reflects the allowNull property of individual attributes).

API

Note: Examples below assume the following [fairly standard] setup code for Sequelize:

// Import this module
const sjs = require('sequelize-json-schema');

// Import Sequelize thingz
const Sequelize = require('Sequelize');
const {DataTypes} = Sequelize;

// Create a sequelize instance
const sequelize = new Sequelize('database', 'username', 'password', {dialect: 'sqlite'});

getSequelizeSchema(sequelize[, options])


`sequelize`	`Sequelize` A Sequelize instance
`options.useRefs`	Default for `useRefs` model option
`options.attributes`	Default for `attributes` model option
`options.exclude`	Default for `exclude` model option
`options.modelOptions`	Model-specific options
(returns)	`Object` JSON Schema object

Example

Schema for simple one-model schema:

const Person = sequelize.define('Person', {name: DataTypes.STRING});

console.log(sjs.getSequelizeSchema(sequelize));

⇒ {
⇒   '$schema': 'http://json-schema.org/draft-07/schema#',
⇒   type: 'object',
⇒   definitions: {
⇒     Person: {
⇒       type: 'object',
⇒       properties: {
⇒         id: { type: 'integer', format: 'int32' },
⇒         name: { type: [ 'string', 'null' ], maxLength: 255 },
⇒         createdAt: { type: 'string', format: 'date-time' },
⇒         updatedAt: { type: 'string', format: 'date-time' }
⇒       },
⇒       required: [ 'id', 'createdAt', 'updatedAt' ]
⇒     }
⇒   }
⇒ }

... continuing on, use options to exclude a few properties:

const options = {exclude: ['id', 'createdAt', 'updatedAt']};

console.log(sjs.getSequelizeSchema(sequelize, options));

⇒ {
⇒   '$schema': 'http://json-schema.org/draft-07/schema#',
⇒   type: 'object',
⇒   definitions: {
⇒     Person: {
⇒       type: 'object',
⇒       properties: { name: { type: [ 'string', 'null' ], maxLength: 255 } }
⇒     }
⇒   }
⇒ }

... continuing on, add another model and some associations:

const Address = sequelize.define('Address', {
  street: DataTypes.STRING('tiny'),
  city: DataTypes.STRING,
  state: {type: DataTypes.STRING(2)},
  zipcode: DataTypes.NUMBER,
});

Person.hasOne(Address);
Address.hasMany(Person);

console.log(sjs.getSequelizeSchema(sequelize, options));

⇒ {
⇒   '$schema': 'http://json-schema.org/draft-07/schema#',
⇒   type: 'object',
⇒   definitions: {
⇒     Person: {
⇒       type: 'object',
⇒       properties: {
⇒         name: { type: [ 'string', 'null' ], maxLength: 255 },
⇒         Address: { '$ref': '#/definitions/Address' }
⇒       }
⇒     },
⇒     Address: {
⇒       type: 'object',
⇒       properties: {
⇒         street: { type: [ 'string', 'null' ], maxLength: 255 },
⇒         city: { type: [ 'string', 'null' ], maxLength: 255 },
⇒         state: { type: [ 'string', 'null' ], maxLength: 2 },
⇒         zipcode: { type: [ 'number', 'null' ] },
⇒         People: { type: 'array', items: { '$ref': '#/definitions/Person' } }
⇒       }
⇒     }
⇒   }
⇒ }

... continuing (customizing with options and modelOptions):

console.log(sjs.getSequelizeSchema(sequelize, {
  exclude: ['createdAt', 'updatedAt'],
  modelOptions: {
    Person: {exclude: ['id']},
    Address: {attributes: ['id']},
  }
}));

⇒ {
⇒   '$schema': 'http://json-schema.org/draft-07/schema#',
⇒   type: 'object',
⇒   definitions: {
⇒     Person: {
⇒       type: 'object',
⇒       properties: {
⇒         name: { type: [ 'string', 'null' ], maxLength: 255 },
⇒         Address: { '$ref': '#/definitions/Address' }
⇒       }
⇒     },
⇒     Address: {
⇒       type: 'object',
⇒       properties: { id: { type: 'integer', format: 'int32' } },
⇒       required: [ 'id' ]
⇒     }
⇒   }
⇒ }

getModelSchema(model[, options])


`model`	`Sequelize.Model`
`options`	`Object`
`options.useRefs`	`Boolean = true` Determines how associations are described in the schema. If true, `model.associations` are described as `$ref`s to the appropriate entry in the schema `definitions`. If false, assiciations are described as plain attributes
`options.attributes`	`Array` Attributes to include in the schema
`options.exclude`	`Array` Attributes to exclude from the schema
(return)	`Object` JSON Schema definition for the model

Example

... continuing getSequelizeSchema() example, above:

console.log(sjs.getModelSchema(Person));

⇒ {
⇒   type: 'object',
⇒   properties: {
⇒     id: { type: 'integer', format: 'int32' },
⇒     name: { type: [ 'string', 'null' ], maxLength: 255 },
⇒     createdAt: { type: 'string', format: 'date-time' },
⇒     updatedAt: { type: 'string', format: 'date-time' },
⇒     Address: { '$ref': '#/definitions/Address' }
⇒   },
⇒   required: [ 'id', 'createdAt', 'updatedAt' ]
⇒ }

... continuing (useRefs = false to treat associations as plain attributes):

console.log(sjs.getModelSchema(Person, {useRefs: false}));

⇒ {
⇒   type: 'object',
⇒   properties: {
⇒     id: { type: 'integer', format: 'int32' },
⇒     name: { type: [ 'string', 'null' ], maxLength: 255 },
⇒     createdAt: { type: 'string', format: 'date-time' },
⇒     updatedAt: { type: 'string', format: 'date-time' },
⇒     AddressId: { type: [ 'integer', 'null' ], format: 'int32' }
⇒   },
⇒   required: [ 'id', 'createdAt', 'updatedAt' ]
⇒ }

getAttributeSchema(attribute)


`attribute`	`Sequelize.Model attribute`
(returns)	`Object` JSON Schema property for the attribute

Example

... continuing getModelSchema() example, above:

console.log(sjs.getAttributeSchema(Person.rawAttributes.name));

⇒ { type: [ 'string', 'null' ], maxLength: 255 }

Markdown generated from README_js.md by

dekelev / sequelize-json-schema Goto Github PK