No description or website provided.
Branch: master
Clone or download
DScheglov 1.2.1
[dsch] fix in tests for node@4.x.x -- trailing comas have been removed
Latest commit b1a8446 Dec 3, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib 1.2.0 Dec 3, 2018
samples v.1.1.1 with mongoose.Query support Dec 2, 2016
test 1.2.1 Dec 3, 2018
.gitignore
.travis.yml 1.1.15 Feb 22, 2018
LICENSE v.1.1.1 - travis integration Dec 16, 2016
index.js v.1.1.1 with mongoose.Query support Dec 2, 2016
package.json 1.2.1 Dec 3, 2018
readme.md
test.sh coveralls reporting Dec 19, 2016

readme.md

Build status Coverage Status

mongoose-schema-jsonschema

The module allows to create json schema from Mongoose schema by adding jsonSchema method to mongoose.Schema, mongoose.Model and mongoose.Query classes

Contents


Installation

npm install mongoose-schema-jsonschema

Samples

Let's build json schema from simple mongoose schema

'use strict';

const mongoose = require('mongoose');
require('mongoose-schema-jsonschema')(mongoose);

const Schema = mongoose.Schema;

const BookSchema = new Schema({
  title: {type: String, required: true},
  year: Number,
  author: {type: String, required: true}
});

let jsonSchema = BookSchema.jsonSchema();

console.dir(jsonSchema, {depth: null});

Output:

{
  type: 'object',
  properties: {
    title: { type: 'string' },
    year: { type: 'number' },
    author: { type: 'string' },
    _id: { type: 'string', pattern: '^[0-9a-fA-F]{24}$' }
  },
  required: [ 'title', 'author' ]
}

The mongoose.Model.jsonSchema method allows to build json schema considering the field selection and population

'use strict';

const mongoose = require('mongoose');
require('mongoose-schema-jsonschema')(mongoose);

const Schema = mongoose.Schema;

const BookSchema = new Schema({
  title: {type: String, required: true},
  year: Number,
  author: {type: Schema.Types.ObjectId, required: true, ref: 'Person'}
});

const PersonSchema = new Schema({
  firstName: {type: String, required: true},
  lastName: {type: String, required: true},
  dateOfBirth: Date
});

const Book = mongoose.model('Book', BookSchema);
const Person = mongoose.model('Person', PersonSchema)

console.dir(Book.jsonSchema('title year'), {depth: null});
console.dir(Book.jsonSchema('', 'author'), {depth: null});

Output:

{
  title: 'Book',
  type: 'object',
  properties: {
    title: { type: 'string' },
    year: { type: 'number' },
    _id: { type: 'string', pattern: '^[0-9a-fA-F]{24}$' }
  }
}
{
  title: 'Book',
  type: 'object',
  properties: {
    title: { type: 'string' },
    year: { type: 'number' },
    author: {
      title: 'Person',
      type: 'object',
      properties: {
        firstName: { type: 'string' },
        lastName: { type: 'string' },
        dateOfBirth: { type: 'string', format: 'date-time' },
        _id: { type: 'string', pattern: '^[0-9a-fA-F]{24}$' },
        __v: { type: 'number' }
      },
      required: [ 'firstName', 'lastName' ],
      'x-ref': 'Person',
      description: 'Refers to Person'
    },
    _id: { type: 'string', pattern: '^[0-9a-fA-F]{24}$' },
    __v: { type: 'number' }
  },
  required: [ 'title', 'author' ]
}
'use strict';

const extendMongooose = require('mongoose-schema-jsonschema');
const mongoose = extendMongooose(require('mongoose'));

const Schema = mongoose.Schema;

const BookSchema = new Schema({
  title: {type: String, required: true},
  year: Number,
  author: {type: Schema.Types.ObjectId, required: true, ref: 'Person'}
});

const Book = mongoose.model('Book', BookSchema);
const Q = Book.find().select('title').limit(5);


console.dir(Q.jsonSchema(), {depth: null});

Output:

{
  title: 'List of books',
  type: 'array',
  items: {
    type: 'object',
    properties: {
      title: { type: 'string' },
      _id: { type: 'string', pattern: '^[0-9a-fA-F]{24}$' }
    }
  },
  maxItems: 5
}

Validation tools

Created by mongoose-schema-jsonschema json-schema's could be used for document validation with:

Specifications

mongoose.Schema.prototype.jsonSchema

Builds the json schema based on the Mongooose schema. if schema has been already built the method returns new deep copy

Method considers the schema.options.toJSON.virtuals to included the virtual paths (without detailed description)

Declaration:

function schema_jsonSchema(name) { ... }

Parameters:

  • name: String - Name of the object
  • Returns Object - json schema

mongoose.Model.jsonSchema

Builds json schema for model considering the selection and population

if fields specified the method removes required constraints

Declaration:

function model_jsonSchema(fields, populate) { ... }

Parameters:

  • fields: String|Array|Object - mongoose selection object
  • populate: String|Object - mongoose population options
  • Returns Object - json schema

mongoose.Query.prototype.jsonSchema

Builds json schema considering the query type and query options. The method returns the schema for array if query type is find and the schema for single document if query type is findOne or findOneAnd*.

In case when the method returns schema for array the collection name is used to form title of the resulting schema. In findOne* case the title is the name of the appropriate model.

Declaration:

function query_jsonSchema() { ... }

Parameters:

  • Returns Object - json schema

Custom Schema Types Support

If you use custom Schema Types you should define the jsonSchema method for your type-class(es).

The base functionality is accessible from your code by calling base-class methods:

newSchemaType.prototype.jsonSchema = function() {
  // Simple types (strings, numbers, bools):
  var jsonSchema = mongoose.SchemaType.prototype.jsonSchema.call(this);

  // Date:
  var jsonSchema = Types.Date.prototype.jsonSchema.call(this);

  // ObjectId
  var jsonSchema = Types.ObjectId.prototype.jsonSchema.call(this);

  // for Array (or DocumentArray)
  var jsonSchema = Types.Array.prototype.jsonSchema.call(this);

  // for Embedded documents
  var jsonSchema = Types.Embedded.prototype.jsonSchema.call(this);

  // for Mixed documents:
  var jsonSchema = Types.Mixed.prototype.jsonSchema.call(this);

  /*
   *
   * Place your code instead of this comment
   *
   */

   return jsonSchema;
}

Command line

There is a command line utility to build schema without importing mongoose-schema-jsonschema to your project

npm i -g jsonschema-builder

Usage

Getting options:

jsonschema-builder --help

Output:

  Usage: jsonschema-builder [options] <pathToModels>

  Options:

    -h, --help     output usage information
    -V, --version  output the version number
    -j, --json     JSON format for output
    -n, --noid     Removes id field from resulting schema

Samples and other details can be reached by the link: jsonschema-builder

Releases:

  • version 1.0 - Basic functionality
  • version 1.1 - Mongoose.Query support implemented
  • version 1.1.5 - uuid issue fixed, ajv compliance verified
  • version 1.1.8 - Schema.Types.Mixed issue fixed
  • version 1.1.9 - readonly settings support added
  • version 1.1.11 - required issue fixed issue#2
  • version 1.1.12 - mixed-type fields description and title support added (fix for issue: issue#3)
  • version 1.1.15 - support for mongoose@5.x ensured issue#8

Supported versions:

  • node.js: 4.x, 5.x, 6.x, 8.x, 9.x
  • mongoose: 4.x, 5.x