Skip to content

alt3/sequelize-to-json-schemas

Repository files navigation

NPM Version Build Status Known Vulnerabilities NPM Total Downloads Code Coverage Code Climate maintainability Conventional Commits Contributor Covenant

sequelize-to-json-schemas

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

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;
};

Framework Integrations


License

This project is released under MIT LICENSE.

Contributing

Please refer to the guidelines for contributing.