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