{"id":13725871,"url":"https://github.com/swagger-model-validator/swagger-model-validator","last_synced_at":"2025-04-18T23:37:36.560Z","repository":{"id":22215411,"uuid":"25548153","full_name":"swagger-model-validator/swagger-model-validator","owner":"swagger-model-validator","description":"A javascript validator for Swagger Models","archived":false,"fork":false,"pushed_at":"2023-03-15T19:38:40.000Z","size":301,"stargazers_count":65,"open_issues_count":9,"forks_count":38,"subscribers_count":19,"default_branch":"master","last_synced_at":"2024-10-16T19:12:21.399Z","etag":null,"topics":["javascript","nodejs","openapi","swagger","swagger-model"],"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/swagger-model-validator.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","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}},"created_at":"2014-10-21T21:54:58.000Z","updated_at":"2023-05-30T18:01:19.000Z","dependencies_parsed_at":"2024-02-04T16:19:37.369Z","dependency_job_id":"4c51d922-59f5-4674-aabd-d9ed30b20919","html_url":"https://github.com/swagger-model-validator/swagger-model-validator","commit_stats":null,"previous_names":["atlantishealthcare/swagger-model-validator"],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swagger-model-validator%2Fswagger-model-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swagger-model-validator%2Fswagger-model-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swagger-model-validator%2Fswagger-model-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swagger-model-validator%2Fswagger-model-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swagger-model-validator","download_url":"https://codeload.github.com/swagger-model-validator/swagger-model-validator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249184863,"owners_count":21226473,"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":["javascript","nodejs","openapi","swagger","swagger-model"],"created_at":"2024-08-03T01:02:38.292Z","updated_at":"2025-04-18T23:37:36.535Z","avatar_url":"https://github.com/swagger-model-validator.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Validate incoming objects against OpenAPI Models for Node.js\n\n\n[ ![npm version](https://badge.fury.io/js/swagger-model-validator.svg)](https://badge.fury.io/js/swagger-model-validator)\n[![Build Status](https://travis-ci.com/swagger-model-validator/swagger-model-validator.svg?branch=master)](https://travis-ci.org/swagger-model-validator/swagger-model-validator)\n[![Known Vulnerabilities](https://snyk.io/test/npm/swagger-model-validator/3.0.15/badge.svg)](https://snyk.io/test/npm/swagger-model-validator/3.0.21)\n[![All Contributors](https://img.shields.io/badge/all_contributors-14-orange.svg?style=flat-square)](https://github.com/swagger-model-validator/swagger-model-validator/blob/master/contributors.md)\n\n[![NPM](https://nodei.co/npm/swagger-model-validator.png?downloads=true)](https://nodei.co/npm-dl/swagger-model-validator/)\n\nThis is a validation module for [Swagger](https://github.com/swagger-api/swagger-spec) models (version 1.2 and 2.0) and for [Open API](https://swagger.io/specification/) models (version 3.0) for Node.js and has been developed using WebStorm.\n\nThe latest version is backwards compatible with all previous releases and supports all versions of Swagger (1.2 and 2.0) and Open API (3.0).  We will try and keep it backward compatible in the future as well.  \nWe will increment the Major and Minor versions to match the maximum version of the Open API supported (currently 3.0).\n\nSee the [swagger-node-express](https://github.com/swagger-api/swagger-node-express) sample for more details about Swagger in Node.js.\n\nThis is tested against and the latest stable versions of NodeJS 4, 5, 6, 7, 8, 9, 10, 11, 12 and 13 using [Travis](https://travis-ci.org/swagger-model-validator/swagger-model-validator).\n\n## What's Open API?\nThe goal of OpenAPI™ (formerly Swagger) is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, OpenAPI removes the guesswork in calling the service.\n\nCheck out [OpenAPI-Spec](https://github.com/OAI/OpenAPI-Specification) for additional information about the OpenAPI project, including additional libraries with support for other languages and more. \n\n## Validating OpenAPI Models?\nAn OpenAPI Model contains the definitions of the incoming (or outgoing) object properties.  Validating an incoming object matches the OpenAPI Model Definition is a valuable check that the correct data has been provided.\n\nThis package provides a module to do just that.\n\n## Swagger and OpenAPI Versions\nThis project should work against both Swagger 1.2, Swagger 2.0 and parts of OpenApi 3.0.  Please create a pull request if you have any fixes for Swagger 2.0 or OpenAPI 3.0 support but please remember to retain support for Swagger 1.2 as well.\n\n### Swagger 1.2\nThis package was original developed against the Swagger 1.2 specification.\n### Swagger 2.0 / OpenAPI 2.0\nThis package has had some activity to align it with the 2.0 specification but it has not been completely done.  We've handled it on an 'as required' basis.  We welcome any pull requests for 2.0 support.\nVersion 2.2.0 has changes that implement the `exclusiveMinimum` and `exclusiveMaximum` validations as per the Swagger 2.0 specification which is different from 1.1 and 3.0 due to changes in the underlying JSON Schema definitions.\n`exclusiveMinimum` and `exclusiveMaximum` can be booleans (Swagger 2.0) which modify the behaviour of the `minimum` and 'maximum' validations; or they can be integers (Swagger 1.1 and OpenAPI 3.0) which set specific exclusive minimums and maximums.\n### OpenAPI 3.0\nThis package has had some activity to align it with the Open API 3.0 specification but it has not been completely done. We welcome any pull requires with 3.0 support but would like to request that you retain support for 1.2 and 2.0 if possible.\n\nRegEx Pattern support was added (Thanks @julianpellasrice)\n\n## Node Versions\nThis package is only compatible with Node 0.10, 0.12 and IO.JS up to version 3.0.10.\n\nFrom version 3.0.11 it is not compatible with those versions of node (or with IO.JS).\n\nVersion 3.0.11 introduced a dependency on Lodash.IsEqual to check that array items are unique (if the uniqueItems property is set to true).  (Thanks @baudicj)\n\n## Validation Notes\nIt will validate int32 properly but the way javascript handles int64 makes it impossible to accurately validate int64s.\nAs long as the value can be parsed by parseInt in javascript it will be accepted as an int64.\n\nIt currently treats float and decimal the same but this is because javascript cannot cope with a decimal (at the moment).\nAs long as the value can be parsed by parseFloat in javascript it will be accepted as a float or a decimal.\n\nIt validates the date and date-time correctly.  It treats all dates (and date-times) as dates and tests with a parseDate\ncheck.  If this passes then it checks 'date' format against a length of 10 (a quick check against the ISO8601 standard, a full-date must be 10 characters long).\n\nAs from version 0.3 it will now validate models referenced by the $ref keyword but it will only do this if it is called\nby the swagger function validateModel or if the native validate is called with a model array passed in.\n\nAs from version 1.0.0 it will now validate arrays in models.  It will validate arrays of a type and arrays of a $ref.\n\nAs from version 2.1.5 it will validate models using the ```allOf``` keyword.\n\nAs from version 3.0.8 it will validate models using the ```oneOf``` keyword.\n## Installation\nInstall swagger-model-validator\n\n```\nnpm install swagger-model-validator\n```\n\nCreate a validator and pass your swagger client into it.\n```\nvar Validator = require('swagger-model-validator');\nvar validator = new Validator(swagger);\n```\n\nNow you can call validateModel on swagger to validate an incoming json object.\n\n```\nvar validation = swagger.validateModel(\"modelName\", jsonObject, _allowBlankTarget_, _disallowExtraProperties_);\n```\n\nThis returns a validation results object\n\n```\n{\n  valid: true,\n  errorCount: 0\n}\n```\nor if validation fails\n```\n{\n  valid: false,\n  errorCount: 2,\n  errors: [\n    {\n      name: 'Error',\n      message: 'An error occurred'\n    },\n    {\n      name: 'Error',\n      message: 'Another error occurred'\n    }\n  ]\n}\n```\n\nYou can also call the validation directly\n\n```\nvar validation = validator.validate(object, swaggerModel, swaggerModels, allowBlankTarget, disallowExtraProperties);\n```\n\nwill return the same validation results but requires the actual swagger model and not its name.  _The swaggerModels\nparameter is required if you want models referenced by the $ref keyword to be validated as well._\n\n## Allowing blank targets to validate\nFrom 1.0.2 any empty objects passed in as targets will fail validation.  You can bypass this by adding a `true` value to\nthe method at the end.\n\n```\nvar validation = swagger.validateModel(\"modelName\", target, true);\n```\n\nThis will allow an empty object `{ }` to be validated without errors. We consider a blank object to be worthless in most\ncases and so should normally fail, but there is always the chance that it might not be worthless so we've added the bypass.\n\n## Preventing extra properties\nFrom 1.2 an optional parameter can be passed into the validation request to control if extra properties should be disallowed.\nIf this flag is true then the target object cannot contain any properties that are not defined on the model.\nIf it is blank or false then the target object __can__ include extra properties (this is the default behaviour and the same\nas pre 1.2)\n\n```\nvar validation = swagger.validateModel(\"modelName\", target, true, true);\n```\n\n## Added support for x-nullable required properties\nFrom 2.1.4 you can add a custom specification to allow a required object to be null.\nThis is different from not being present in the body of the request or response.\n\nSimply add the property ```'x-nullable': true``` to your definition of a required property to allow the value of null to pass validation.\nThis has no effect on any property that is not required.\n\n## Added Support for nullable required properties\nFrom 3.0.5 you can use the nullable property to allow a required object to be null.\nThis works exactly the same was as x-nullable.\n\n```\n'nullable': true\n```\n\nThis change has also added the support for using this (and x-nullable) with a false value.  Previously this would have been the same as true.\n\n## Skip validation of a single field\nFrom 3.0.1 you can add a custom specification to prevent a field being validated.\n\nSimply add the property ```'x-do-not-validate': true``` to your  definition of a property to prevent the property being validated.\n\n## Custom Field Validators\nYou can add a custom field validator for a model to the validator from version 1.0.3 onwards.  This allows you to add a\nfunction that will be called for any specific field that you need validated with extra rules.\n\nThis function should be in the form\n```\nfunction(name, value) {\n  if(error) {\n    return new Error(error);\n  } else {\n    return null;\n  }\n}\n```\nIt can return either a single Error object or an array of error objects.  These errors will be passed back through the\nvalidator to the end user.\n\n### Adding a field validator\nSimply make a call to the validator method ```addFieldValidator``` providing the ```modelName```, ```fieldName``` and\nthe validation function.\n\n```\nvalidator.addFieldValidator(\"testModel\", \"id\", function(name, value) {\n    var errors = []\n    if(value === 34) {\n        errors.push(new Error(\"Value Cannot be 34\"));\n    }\n\n    if(value \u003c 40) {\n        errors.push(new Error(\"Value must be at least 40\"));\n    }\n\n    return errors.length \u003e 0 ? errors : null;\n});\n```\nNow the validator will call this extra function for the 'id' field in the 'testModel' model.\n\nYou can add multiple custom validators to the same field.  They will all be run.  If a validator throws an exception it\nwill be ignored and validation will continue.\n\n### Custom Field Validators for OpenAPI 2.0 Onwards\nBecause the id property has been dropped from the model it is much harder to link models together in the validator.\n\nYou can now add field validators as a custom property on each model by using the addFieldValidatorToModel function.\n\n```\nvalidator.addFieldValidatorToModel(model, \"id\", function(name, value) {\n    var errors = []\n    if(value === 34) {\n        errors.push(new Error(\"Value Cannot be 34\"));\n    }\n\n    if(value \u003c 40) {\n        errors.push(new Error(\"Value must be at least 40\"));\n    }\n\n    return errors.length \u003e 0 ? errors : null;\n});\n```\n\n## Handling Returned Errors\nBe careful with the results as javascript Errors cannot be turned into JSON without losing the message property.\n\nWe have added two methods to help with this.\n\nGetErrorMessages() which returns an array of strings (one for each error) which contain the text of the error.message property.\nGetFormattedErrors() which returns an array of objects (one for each error) which contains all of the custom properties for each error and the text of the error.message property.\n\nJust passing the Validation Response errors array out will result in the loss of the error.message property.  Most errors would appear as empty objects.\n\n## License\nCopyright (c) 2014 Atlantis Healthcare Limited.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswagger-model-validator%2Fswagger-model-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswagger-model-validator%2Fswagger-model-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswagger-model-validator%2Fswagger-model-validator/lists"}