@alt3/sequelize-to-json-schemas NPM

NPM Total Downloads

sequelize-to-json-schemas

Convert Sequelize models into these JSON Schema variants (using the Strategy Pattern):

JSON Schema Draft-07 - sample output
OpenAPI 3.0 - sample output

Compatible with Sequelize versions 4, 5 and 6.

Main Goals

understandable code, highly maintainable
valid schemas (enforced by the ajv and Swagger Parser validators)
JsonSchemaManager for single (rock solid) core functionality shared between all strategies
StrategyInterface for simplified implementation of new schema variants

Feel free to PR strategies for missing schemas

Installation

npm install @alt3/sequelize-to-json-schemas --save

Usage

const { JsonSchemaManager, JsonSchema7Strategy, OpenApi3Strategy } = require('@alt3/sequelize-to-json-schemas');
const schemaManager = new JsonSchemaManager();

// now generate a JSON Schema Draft-07 model schema
let schema = schemaManager.generate(userModel, new JsonSchema7Strategy());

// and/or the OpenAPI 3.0 equivalent
schema = schemaManager.generate(userModel, new OpenApi3Strategy());

Configuration Options

To configure global options use the JsonSchemaManager initialization:

const schemaManager = new JsonSchemaManager({
  baseUri: '/',
  absolutePaths: true,
  secureSchemaUri: true,
  disableComments: true,
});

To configure (per) model options use the generate() method:

const userSchema = schemaManager.generate(userModel, strategy, {
  title: 'Custom model title',
  description: 'Custom model description',
  exclude: ['someAttribute'],
  include: ['someAttribute'],
  associations: true,
  excludeAssociations: ['someAssociation'],
  includeAssociations: ['someAssociation'],
});

The following Sequelize attribute options are automatically converted into schema properties:

module.exports = (sequelize) => {
  const model = sequelize.define('user', {
    userName: {
      type: DataTypes.STRING,
      allowNull: true,
      defaultValue: 'Default Value',
      associate: {},
    },
  });

  return model;
};

To configure additional schema properties add a jsonSchema property with one or more of the following custom options to your Sequelize attribute:

module.exports = (sequelize) => {
  const model = sequelize.define('user', {
    userName: {
      type: DataTypes.STRING,
      jsonSchema: {
        description: 'Custom attribute description',
        comment: 'Custom attribute comment',
        examples: ['Custom example 1', 'Custom example 2'],
        readOnly: true, // OR writeOnly: true
      },
    },
  });

  return model;
};

In order to create a valid output for JSON columns, or to otherwise override the schema output for a particular sequelize attribute, add a schema attribute:

module.exports = (sequelize) => {
  const model = sequelize.define('user', {
    // ...
    settings: {
      type: DataTypes.JSON,
      jsonSchema: {
        schema: { type: 'object' },
      },
    },
  });

  return model;
};