1<div align="center"> 2 <a href="http://json-schema.org"> 3 <img width="160" height="160" 4 src="https://raw.githubusercontent.com/webpack-contrib/schema-utils/master/.github/assets/logo.png"> 5 </a> 6 <a href="https://github.com/webpack/webpack"> 7 <img width="200" height="200" 8 src="https://webpack.js.org/assets/icon-square-big.svg"> 9 </a> 10</div> 11 12[![npm][npm]][npm-url] 13[![node][node]][node-url] 14[![deps][deps]][deps-url] 15[![tests][tests]][tests-url] 16[![coverage][cover]][cover-url] 17[![chat][chat]][chat-url] 18[![size][size]][size-url] 19 20# schema-utils 21 22Package for validate options in loaders and plugins. 23 24## Getting Started 25 26To begin, you'll need to install `schema-utils`: 27 28```console 29npm install schema-utils 30``` 31 32## API 33 34**schema.json** 35 36```json 37{ 38 "type": "object", 39 "properties": { 40 "option": { 41 "type": ["boolean"] 42 } 43 }, 44 "additionalProperties": false 45} 46``` 47 48```js 49import schema from './path/to/schema.json'; 50import validate from 'schema-utils'; 51 52const options = { option: true }; 53const configuration = { name: 'Loader Name/Plugin Name/Name' }; 54 55validate(schema, options, configuration); 56``` 57 58### `schema` 59 60Type: `String` 61 62JSON schema. 63 64Simple example of schema: 65 66```json 67{ 68 "type": "object", 69 "properties": { 70 "name": { 71 "description": "This is description of option.", 72 "type": "string" 73 } 74 }, 75 "additionalProperties": false 76} 77``` 78 79### `options` 80 81Type: `Object` 82 83Object with options. 84 85```js 86validate( 87 schema, 88 { 89 name: 123, 90 }, 91 { name: 'MyPlugin' } 92); 93``` 94 95### `configuration` 96 97Allow to configure validator. 98 99There is an alternative method to configure the `name` and`baseDataPath` options via the `title` property in the schema. 100For example: 101 102```json 103{ 104 "title": "My Loader options", 105 "type": "object", 106 "properties": { 107 "name": { 108 "description": "This is description of option.", 109 "type": "string" 110 } 111 }, 112 "additionalProperties": false 113} 114``` 115 116The last word used for the `baseDataPath` option, other words used for the `name` option. 117Based on the example above the `name` option equals `My Loader`, the `baseDataPath` option equals `options`. 118 119#### `name` 120 121Type: `Object` 122Default: `"Object"` 123 124Allow to setup name in validation errors. 125 126```js 127validate(schema, options, { name: 'MyPlugin' }); 128``` 129 130```shell 131Invalid configuration object. MyPlugin has been initialised using a configuration object that does not match the API schema. 132 - configuration.optionName should be a integer. 133``` 134 135#### `baseDataPath` 136 137Type: `String` 138Default: `"configuration"` 139 140Allow to setup base data path in validation errors. 141 142```js 143validate(schema, options, { name: 'MyPlugin', baseDataPath: 'options' }); 144``` 145 146```shell 147Invalid options object. MyPlugin has been initialised using an options object that does not match the API schema. 148 - options.optionName should be a integer. 149``` 150 151#### `postFormatter` 152 153Type: `Function` 154Default: `undefined` 155 156Allow to reformat errors. 157 158```js 159validate(schema, options, { 160 name: 'MyPlugin', 161 postFormatter: (formattedError, error) => { 162 if (error.keyword === 'type') { 163 return `${formattedError}\nAdditional Information.`; 164 } 165 166 return formattedError; 167 }, 168}); 169``` 170 171```shell 172Invalid options object. MyPlugin has been initialized using an options object that does not match the API schema. 173 - options.optionName should be a integer. 174 Additional Information. 175``` 176 177## Examples 178 179**schema.json** 180 181```json 182{ 183 "type": "object", 184 "properties": { 185 "name": { 186 "type": "string" 187 }, 188 "test": { 189 "anyOf": [ 190 { "type": "array" }, 191 { "type": "string" }, 192 { "instanceof": "RegExp" } 193 ] 194 }, 195 "transform": { 196 "instanceof": "Function" 197 }, 198 "sourceMap": { 199 "type": "boolean" 200 } 201 }, 202 "additionalProperties": false 203} 204``` 205 206### `Loader` 207 208```js 209import { getOptions } from 'loader-utils'; 210import validateOptions from 'schema-utils'; 211 212import schema from 'path/to/schema.json'; 213 214function loader(src, map) { 215 const options = getOptions(this) || {}; 216 217 validateOptions(schema, options, { 218 name: 'Loader Name', 219 baseDataPath: 'options', 220 }); 221 222 // Code... 223} 224 225export default loader; 226``` 227 228### `Plugin` 229 230```js 231import validateOptions from 'schema-utils'; 232 233import schema from 'path/to/schema.json'; 234 235class Plugin { 236 constructor(options) { 237 validateOptions(schema, options, { 238 name: 'Plugin Name', 239 baseDataPath: 'options', 240 }); 241 242 this.options = options; 243 } 244 245 apply(compiler) { 246 // Code... 247 } 248} 249 250export default Plugin; 251``` 252 253## Contributing 254 255Please take a moment to read our contributing guidelines if you haven't yet done so. 256 257[CONTRIBUTING](./.github/CONTRIBUTING.md) 258 259## License 260 261[MIT](./LICENSE) 262 263[npm]: https://img.shields.io/npm/v/schema-utils.svg 264[npm-url]: https://npmjs.com/package/schema-utils 265[node]: https://img.shields.io/node/v/schema-utils.svg 266[node-url]: https://nodejs.org 267[deps]: https://david-dm.org/webpack/schema-utils.svg 268[deps-url]: https://david-dm.org/webpack/schema-utils 269[tests]: https://dev.azure.com/webpack/schema-utils/_apis/build/status/webpack.schema-utils?branchName=master 270[tests-url]: https://dev.azure.com/webpack/schema-utils/_build/latest?definitionId=9&branchName=master 271[cover]: https://codecov.io/gh/webpack/schema-utils/branch/master/graph/badge.svg 272[cover-url]: https://codecov.io/gh/webpack/schema-utils 273[chat]: https://badges.gitter.im/webpack/webpack.svg 274[chat-url]: https://gitter.im/webpack/webpack 275[size]: https://packagephobia.now.sh/badge?p=schema-utils 276[size-url]: https://packagephobia.now.sh/result?p=schema-utils 277