# sequelize-json-schema

> Use your Sequelize models in JSON Schemas or Swagger

Latest version **2.1.1** (published 2020-01-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install sequelize-json-schema
pnpm add sequelize-json-schema
yarn add sequelize-json-schema
bun add sequelize-json-schema
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 2.1.1 |
| Published | 2020-01-10 |
| First published | 2016-07-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 8 |
| Dependencies | 0 |
| Unpacked size | 18.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 34 |
| Author | Robert Kieffer |
| Maintainers | chaliy |
| Keywords | sequelize, json, json-schema, swagger |

## Links

- npm: https://www.npmjs.com/package/sequelize-json-schema
- Repository: https://github.com/chaliy/sequelize-json-schema
- Homepage: https://github.com/chaliy/sequelize-json-schema#readme
- Issues: https://github.com/chaliy/sequelize-json-schema/issues
- npm.io page: https://npm.io/package/sequelize-json-schema

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 2.1.1 (latest) — 2020-01-10
- 2.1.0 — 2020-01-10
- 2.0.0 — 2019-12-30
- 1.3.0 — 2017-10-16
- 1.2.0 — 2016-12-21
- 1.1.0 — 2016-12-16
- 1.0.2 — 2016-12-16
- 1.0.1 — 2016-07-29
- 1.0.0 — 2016-07-24

## README

<!--
  -- This file is auto-generated from README_js.md. Changes should be made there.
  -->

# sequelize-json-schema

[![NPM Version](https://img.shields.io/npm/v/sequelize-json-schema.svg)](https://npmjs.org/package/sequelize-json-schema)
[![CircleCI](https://circleci.com/gh/chaliy/sequelize-json-schema.svg?style=svg)](https://circleci.com/gh/chaliy/sequelize-json-schema)

Generate [JSON Schema](https://json-schema.org/) 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

```bash
npm install sequelize-json-schema
```

## Migrating v1 &rarr; 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:
```javascript
// 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:
```javascript
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:
```javascript
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:

```javascript
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`):

```javascript
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` | Sequelize model instance |
| `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:

```javascript
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):

```javascript
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:

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

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


----
Markdown generated from [README_js.md](README_js.md) by [![RunMD Logo](http://i.imgur.com/h0FVyzU.png)](https://github.com/broofa/runmd)

---
_Source: https://npm.io/package/sequelize-json-schema · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._