{"id":14975673,"url":"https://github.com/dscheglov/mongoose-schema-jsonschema","last_synced_at":"2025-05-16T05:04:48.621Z","repository":{"id":38420556,"uuid":"69676933","full_name":"DScheglov/mongoose-schema-jsonschema","owner":"DScheglov","description":"Mongoose extension that allows to build json schema for mongoose models, schemes and queries","archived":false,"fork":false,"pushed_at":"2024-10-14T10:36:33.000Z","size":166,"stargazers_count":107,"open_issues_count":6,"forks_count":31,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-12T13:07:08.787Z","etag":null,"topics":["json","json-schema","mongoose","mongoose-schema","mongoose-schema-jsonschema","population"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DScheglov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-30T15:07:37.000Z","updated_at":"2024-10-14T10:36:37.000Z","dependencies_parsed_at":"2022-09-20T14:54:07.408Z","dependency_job_id":"b32649d5-a828-4386-b25a-46ad678e6fa5","html_url":"https://github.com/DScheglov/mongoose-schema-jsonschema","commit_stats":{"total_commits":111,"total_committers":6,"mean_commits":18.5,"dds":0.06306306306306309,"last_synced_commit":"d7768f4b61c068d4b0ddbb5de8612702f75dc26d"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DScheglov%2Fmongoose-schema-jsonschema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DScheglov%2Fmongoose-schema-jsonschema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DScheglov%2Fmongoose-schema-jsonschema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DScheglov%2Fmongoose-schema-jsonschema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DScheglov","download_url":"https://codeload.github.com/DScheglov/mongoose-schema-jsonschema/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254471060,"owners_count":22076585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","json-schema","mongoose","mongoose-schema","mongoose-schema-jsonschema","population"],"created_at":"2024-09-24T13:52:22.387Z","updated_at":"2025-05-16T05:04:48.602Z","avatar_url":"https://github.com/DScheglov.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Build Status](https://github.com/DScheglov/mongoose-schema-jsonschema/actions/workflows/run-tests.yml/badge.svg)\r\n[![Coverage Status](https://coveralls.io/repos/github/DScheglov/mongoose-schema-jsonschema/badge.svg?branch=master)](https://coveralls.io/github/DScheglov/)\r\n[![npm downloads](https://img.shields.io/npm/dm/mongoose-schema-jsonschema)](https://www.npmjs.com/package/mongoose-schema-jsonschema)\r\n[![NPM](https://img.shields.io/npm/l/mongoose-schema-jsonschema)](https://github.com/DScheglov/mongoose-schema-jsonschema/blob/master/LICENSE)\r\n\r\n# mongoose-schema-jsonschema\r\n\r\nThe module allows to create json schema from Mongoose schema by adding\r\n`jsonSchema` method to `mongoose.Schema`, `mongoose.Model` and `mongoose.Query`\r\nclasses\r\n\r\n## Contents\r\n\r\n- [mongoose-schema-jsonschema](#mongoose-schema-jsonschema)\r\n  - [Contents](#contents)\r\n  - [Installation](#installation)\r\n  - [Schema Build Configuration](#schema-build-configuration)\r\n  - [Samples](#samples)\r\n  - [Validation tools](#validation-tools)\r\n  - [Specifications](#specifications)\r\n    - [mongoose.Schema.prototype.jsonSchema](#mongooseschemaprototypejsonschema)\r\n    - [mongoose.Model.jsonSchema](#mongoosemodeljsonschema)\r\n    - [mongoose.Query.prototype.jsonSchema](#mongoosequeryprototypejsonschema)\r\n  - [Custom Schema Types Support](#custom-schema-types-support)\r\n  - [Releases](#releases)\r\n  - [Supported versions](#supported-versions)\r\n\r\n-----------------\r\n\r\n## Installation\r\n\r\n```shell\r\nnpm install mongoose-schema-jsonschema\r\n```\r\n\r\n## Schema Build Configuration\r\n\r\nSince v1.4.0 it is able to configure how `jsonSchema()` works.\r\n\r\nTo do that package was extended with `config` function.\r\n\r\n```js\r\nconst config = require('mongoose-schema-jsonschema/config');\r\n\r\nconfig({\r\n  // ... options go here\r\n});\r\n```\r\n\r\nCurrently there are two options that affects build process:\r\n\r\n- **forceRebuild**: `boolean` -- **mongoose-schema-jsonschema** caches json schemas built for mongoose schemas.\r\n  That means we cannot built updated jsonSchema after some updates were made in the mongoose schema\r\n  that already has jsonSchema.\r\n  To resolve this issue the `forceRebuild` was added (see sample bellow)\r\n\r\n- **fieldOptionsMapping**: `{ [key: string]: string } | Array\u003cstring|[string, string]\u003e` - allows to specify how to convert some custom options specified in the mongoose field definition.\r\n\r\n```js\r\nconst mongoose = require('mongoose-schema-jsonschema')();\r\nconst config = require('mongoose-schema-jsonschema/config');\r\n\r\nconst { Schema } = mongoose;\r\n\r\nconst BookSchema = new Schema({\r\n  title: { type: String, required: true, notes: 'Book Title' },\r\n  year: Number,\r\n  author: { type: String, required: true },\r\n});\r\n\r\nconst fieldOptionsMapping = {\r\n  notes: 'x-notes',\r\n};\r\n\r\nconfig({ fieldOptionsMapping });\r\nconsole.dir(BookSchema.jsonSchema(), { depth: null });\r\n\r\nconfig({ fieldOptionsMapping: [], forceRebuild: true }); // reset\r\nconsole.dir(BookSchema.jsonSchema(), { depth: null });\r\n```\r\n\r\n**Output**:\r\n\r\n```js\r\n{\r\n  type: 'object',\r\n  properties: {\r\n    title: { type: 'string', 'x-notes': 'Book Title' },\r\n    year: { type: 'number' },\r\n    author: { type: 'string' },\r\n    _id: { type: 'string', pattern: '^[0-9a-fA-F]{24}$' }\r\n  },\r\n  required: [ 'title', 'author' ]\r\n}\r\n{\r\n  type: 'object',\r\n  properties: {\r\n    title: { type: 'string' },\r\n    year: { type: 'number' },\r\n    author: { type: 'string' },\r\n    _id: { type: 'string', pattern: '^[0-9a-fA-F]{24}$' }\r\n  },\r\n  required: [ 'title', 'author' ]\r\n}\r\n```\r\n\r\n## Samples\r\n\r\nLet's build json schema from simple mongoose schema\r\n\r\n```javascript\r\nconst mongoose = require('mongoose');\r\nrequire('mongoose-schema-jsonschema')(mongoose);\r\n\r\nconst Schema = mongoose.Schema;\r\n\r\nconst BookSchema = new Schema({\r\n  title: { type: String, required: true },\r\n  year: Number,\r\n  author: { type: String, required: true },\r\n});\r\n\r\nconst jsonSchema = BookSchema.jsonSchema();\r\n\r\nconsole.dir(jsonSchema, { depth: null });\r\n\r\n```\r\n\r\n**Output**:\r\n\r\n```javascript\r\n{\r\n  type: 'object',\r\n  properties: {\r\n    title: { type: 'string' },\r\n    year: { type: 'number' },\r\n    author: { type: 'string' },\r\n    _id: { type: 'string', pattern: '^[0-9a-fA-F]{24}$' }\r\n   },\r\n  required: [ 'title', 'author' ]\r\n}\r\n```\r\n\r\nThe mongoose.Model.jsonSchema method allows to build json schema considering\r\nthe field selection and population\r\n\r\n```javascript\r\nconst mongoose = require('mongoose');\r\nrequire('mongoose-schema-jsonschema')(mongoose);\r\n\r\nconst Schema = mongoose.Schema;\r\n\r\nconst BookSchema = new Schema({\r\n  title: { type: String, required: true },\r\n  year: Number,\r\n  author: { type: Schema.Types.ObjectId, required: true, ref: 'Person' }\r\n});\r\n\r\nconst PersonSchema = new Schema({\r\n  firstName: { type: String, required: true },\r\n  lastName: { type: String, required: true },\r\n  dateOfBirth: Date\r\n});\r\n\r\nconst Book = mongoose.model('Book', BookSchema);\r\nconst Person = mongoose.model('Person', PersonSchema)\r\n\r\nconsole.dir(Book.jsonSchema('title year'), { depth: null });\r\nconsole.dir(Book.jsonSchema('', 'author'), { depth: null });\r\n\r\n```\r\n\r\n**Output**:\r\n\r\n```javascript\r\n{\r\n  title: 'Book',\r\n  type: 'object',\r\n  properties: {\r\n    title: { type: 'string'  },\r\n    year: { type: 'number'  },\r\n    _id: { type: 'string', pattern: '^[0-9a-fA-F]{24}$' }\r\n  }\r\n}\r\n{\r\n  title: 'Book',\r\n  type: 'object',\r\n  properties: {\r\n    title: { type: 'string'  },\r\n    year: { type: 'number'  },\r\n    author: {\r\n      title: 'Person',\r\n      type: 'object',\r\n      properties: {\r\n        firstName: { type: 'string'  },\r\n        lastName: { type: 'string'  },\r\n        dateOfBirth: { type: 'string', format: 'date-time'  },\r\n        _id: { type: 'string', pattern: '^[0-9a-fA-F]{24}$'  },\r\n        __v: { type: 'number' }\r\n       },\r\n      required: [ 'firstName', 'lastName' ],\r\n      'x-ref': 'Person',\r\n      description: 'Refers to Person'\r\n     },\r\n    _id: { type: 'string', pattern: '^[0-9a-fA-F]{24}$'  },\r\n    __v: { type: 'number' }\r\n   },\r\n  required: [ 'title', 'author' ]\r\n}\r\n```\r\n\r\n```javascript\r\nconst mongoose = require('mongoose');\r\nconst extendMongoose = require('mongoose-schema-jsonschema');\r\n\r\nextendMongoose(mongoose);\r\n\r\nconst { Schema } = mongoose;\r\n\r\nconst BookSchema = new Schema({\r\n  title: { type: String, required: true  },\r\n  year: Number,\r\n  author: { type: Schema.Types.ObjectId, required: true, ref: 'Person' }\r\n});\r\n\r\nconst Book = mongoose.model('Book', BookSchema);\r\nconst Q = Book.find().select('title').limit(5);\r\n\r\n\r\nconsole.dir(Q.jsonSchema(), { depth: null });\r\n```\r\n\r\n**Output**:\r\n\r\n```javascript\r\n{\r\n  title: 'List of books',\r\n  type: 'array',\r\n  items: {\r\n    type: 'object',\r\n    properties: {\r\n      title: { type: 'string'  },\r\n      _id: { type: 'string', pattern: '^[0-9a-fA-F]{24}$' }\r\n    }\r\n   },\r\n  maxItems: 5\r\n}\r\n```\r\n\r\n## Validation tools\r\n\r\nCreated by **mongoose-schema-jsonschema** json-schema's could be used for\r\ndocument validation with:\r\n\r\n- [`ajv`](https://www.npmjs.com/package/ajv)\r\n- [`jsonschema`](https://www.npmjs.com/package/jsonschema)\r\n\r\n## Specifications\r\n\r\n### mongoose.Schema.prototype.jsonSchema\r\n\r\nBuilds the json schema based on the Mongoose schema.\r\nif schema has been already built the method returns new deep copy\r\n\r\nMethod considers the `schema.options.toJSON.virtuals` to included\r\nthe virtual paths (without detailed description)\r\n\r\nDeclaration:\r\n\r\n```javascript\r\nfunction schema_jsonSchema(name) { ... }\r\n```\r\n\r\nParameters:\r\n\r\n- **name**: `String` -  Name of the object\r\n- *Returns* `Object` - json schema\r\n\r\n### mongoose.Model.jsonSchema\r\n\r\nBuilds json schema for model considering the selection and population\r\n\r\nif `fields` specified the method removes `required` constraints\r\n\r\nDeclaration:\r\n\r\n```javascript\r\nfunction model_jsonSchema(fields, populate) { ... }\r\n```\r\n\r\n Parameters:\r\n\r\n- **fields**: `String`|`Array`|`Object` - mongoose selection object\r\n- **populate**: `String`|`Object` - mongoose population options\r\n- *Returns* `Object` - json schema\r\n\r\n### mongoose.Query.prototype.jsonSchema\r\n\r\n Builds json schema considering the query type and query options.\r\n The method returns the schema for array if query type is `find` and\r\n the schema for single document if query type is `findOne` or `findOneAnd*`.\r\n\r\n In case when the method returns schema for array the collection name is used to\r\n form title of the resulting schema. In `findOne*` case the title is the name\r\n of the appropriate model.\r\n\r\n Declaration:\r\n\r\n ```javascript\r\n function query_jsonSchema() { ... }\r\n ```\r\n\r\n  Parameters:\r\n\r\n- *Returns* `Object` - json schema\r\n\r\n## Custom Schema Types Support\r\n\r\nIf you use custom Schema Types you should define the jsonSchema method\r\nfor your type-class(es).\r\n\r\nThe base functionality is accessible from your code by calling base-class methods:\r\n\r\n```javascript\r\nnewSchemaType.prototype.jsonSchema = function() {\r\n  // Simple types (strings, numbers, bools):\r\n  const jsonSchema = mongoose.SchemaType.prototype.jsonSchema.call(this);\r\n\r\n  // Date:\r\n  const jsonSchema = Types.Date.prototype.jsonSchema.call(this);\r\n\r\n  // ObjectId\r\n  const jsonSchema = Types.ObjectId.prototype.jsonSchema.call(this);\r\n\r\n  // for Array (or DocumentArray)\r\n  const jsonSchema = Types.Array.prototype.jsonSchema.call(this);\r\n\r\n  // for Embedded documents\r\n  const jsonSchema = Types.Embedded.prototype.jsonSchema.call(this);\r\n\r\n  // for Mixed documents:\r\n  const jsonSchema = Types.Mixed.prototype.jsonSchema.call(this);\r\n\r\n  /*\r\n   *\r\n   * Place your code instead of this comment\r\n   *\r\n   */\r\n\r\n   return jsonSchema;\r\n}\r\n```\r\n\r\n## Releases\r\n\r\n- version 1.0 - Basic functionality\r\n- version 1.1 - Mongoose.Query support implemented\r\n- version 1.1.5 - uuid issue fixed, ajv compliance verified\r\n- version 1.1.8 - Schema.Types.Mixed issue fixed\r\n- version 1.1.9 - readonly settings support added\r\n- version 1.1.11 - required issue fixed [issue#2](https://github.com/DScheglov/mongoose-schema-jsonschema/issues/2)\r\n- version 1.1.12 - mixed-type fields description and title support added (fix for issue: [issue#3](https://github.com/DScheglov/mongoose-schema-jsonschema/issues/3))\r\n- version 1.1.15 - support for \u003cmongoose@5.x\u003e ensured [issue#8](https://github.com/DScheglov/mongoose-schema-jsonschema/issues/8)\r\n- version 1.3.0\r\n  - nullable types support (as union: `[type, 'null']`)\r\n  - `examples` option support [issue#14](https://github.com/DScheglov/mongoose-schema-jsonschema/issues/14)\r\n  - support for fields dynamicly marked as `required` [issue#16](https://github.com/DScheglov/mongoose-schema-jsonschema/issues/16)\r\n  - Node support restricted to 8.x, 9.x, 10.x, 12.x\r\n  - Mongoose support restricted to 5.x\r\n  - *Development*:\r\n    - migrated from `mocha` + `istanbul` to `jest`\r\n    - added `eslint`\r\n- version 1.3.1 - support `minlenght` and `maxlength` [issue#21](https://github.com/DScheglov/mongoose-schema-jsonschema/issues/21)\r\n- version 1.4.0 - **broken** - schema build configurations (`forceRebuild` and `fieldOptionsMapping`)\r\n- version 1.4.2 - fix for broken version 1.4.0 [issue#22](https://github.com/DScheglov/mongoose-schema-jsonschema/issues/22)\r\n- version 1.4.4 - fix for field constraints [issue#25](https://github.com/DScheglov/mongoose-schema-jsonschema/issues/25)\r\n- version 2.0.0 - Support for \u003cmongoose@6.x.x\u003e. Node v8.x.x, v9.x.x are no longer supported (use v1.4.7 of the lib)\r\n- version 2.1.0 - Support for \u003cmongoose@7.x.x\u003e and Node v14.x, v16.x, v18.x\r\n- version 2.2.0 - Support for \u003cmongoose@8.x.x\u003e and Node v20.x. Node v14.x is no longer supported (use v2.1.0 of the lib)\r\n- version 2.2.1 - fix for `required` fields: if `required` is a function, it is not considered as required field\r\n- version 3.0.0 - breaking changes on Array with `required`: the `minItems` constraint is removed from JSON schema\r\n\r\n## Supported versions\r\n\r\n- node.js: 16.x, 18.x, 20.x\r\n- mongoose: 5.x, 6.x, 7.x, 8.x\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdscheglov%2Fmongoose-schema-jsonschema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdscheglov%2Fmongoose-schema-jsonschema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdscheglov%2Fmongoose-schema-jsonschema/lists"}