What is schema-utils?
The schema-utils package is a utility library for validating options against a JSON Schema. It is commonly used in the context of webpack loaders and plugins to validate configuration objects. It provides functions to validate options, throw useful errors, and ensure that the configuration adheres to a specified schema.
What are schema-utils's main functionalities?
Validation of options
This feature allows users to validate an options object against a predefined JSON Schema. The 'validate' function takes a schema, options, and a configuration object that includes the name of the plugin or loader using the validation.
const { validate } = require('schema-utils');
const schema = {
type: 'object',
properties: {
name: {
type: 'string'
}
},
required: ['name']
};
const options = { name: 'Example' };
validate(schema, options, { name: 'MyPlugin' });
Custom error messages
This feature allows users to provide custom error messages in the schema that will be displayed when validation fails. The 'validate' function will throw an error with these messages if the options do not match the schema.
const { validate } = require('schema-utils');
const schema = {
type: 'object',
properties: {
age: {
type: 'number',
description: 'Age must be a number'
}
},
required: ['age']
};
const options = { age: 'old' };
try {
validate(schema, options, { name: 'AgeChecker' });
} catch (error) {
// Custom error handling
}
Other packages similar to schema-utils
ajv
Ajv is a JSON schema validator that is fast and supports draft-06/07/2019 JSON Schema. It is more feature-rich and supports more JSON Schema features compared to schema-utils, which is more focused on webpack-related configuration validation.
joi
Joi is an object schema validation library that can validate objects based on a schema with a fluent API. It is different from schema-utils in that it is not specifically tied to JSON Schema and provides a more expressive way to define validation rules and constraints.
yup
Yup is a JavaScript schema builder for value parsing and validation. It defines a schema using a declarative API and is often used in the context of form validation. Unlike schema-utils, Yup is not specifically designed for webpack configurations and offers a different API for schema construction.

schema-utils
Package for validate options in loaders and plugins.
Getting Started
To begin, you'll need to install schema-utils
:
npm install schema-utils
API
schema.json
{
"type": "object",
"properties": {
"option": {
"type": "boolean"
}
},
"additionalProperties": false
}
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";
const options = { option: true };
const configuration = { name: "Loader Name/Plugin Name/Name" };
validate(schema, options, configuration);
schema
Type: String
JSON schema.
Simple example of schema:
{
"type": "object",
"properties": {
"name": {
"description": "This is description of option.",
"type": "string"
}
},
"additionalProperties": false
}
options
Type: Object
Object with options.
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";
const options = { foo: "bar" };
validate(schema, { name: 123 }, { name: "MyPlugin" });
configuration
Allow to configure validator.
There is an alternative method to configure the name
andbaseDataPath
options via the title
property in the schema.
For example:
{
"title": "My Loader options",
"type": "object",
"properties": {
"name": {
"description": "This is description of option.",
"type": "string"
}
},
"additionalProperties": false
}
The last word used for the baseDataPath
option, other words used for the name
option.
Based on the example above the name
option equals My Loader
, the baseDataPath
option equals options
.
name
Type: Object
Default: "Object"
Allow to setup name in validation errors.
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";
const options = { foo: "bar" };
validate(schema, options, { name: "MyPlugin" });
Invalid configuration object. MyPlugin has been initialised using a configuration object that does not match the API schema.
- configuration.optionName should be a integer.
baseDataPath
Type: String
Default: "configuration"
Allow to setup base data path in validation errors.
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";
const options = { foo: "bar" };
validate(schema, options, { name: "MyPlugin", baseDataPath: "options" });
Invalid options object. MyPlugin has been initialised using an options object that does not match the API schema.
- options.optionName should be a integer.
postFormatter
Type: Function
Default: undefined
Allow to reformat errors.
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";
const options = { foo: "bar" };
validate(schema, options, {
name: "MyPlugin",
postFormatter: (formattedError, error) => {
if (error.keyword === "type") {
return `${formattedError}\nAdditional Information.`;
}
return formattedError;
},
});
Invalid options object. MyPlugin has been initialized using an options object that does not match the API schema.
- options.optionName should be a integer.
Additional Information.
Examples
schema.json
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"test": {
"anyOf": [
{ "type": "array" },
{ "type": "string" },
{ "instanceof": "RegExp" }
]
},
"transform": {
"instanceof": "Function"
},
"sourceMap": {
"type": "boolean"
}
},
"additionalProperties": false
}
Loader
import { getOptions } from "loader-utils";
import { validate } from "schema-utils";
import schema from "path/to/schema.json";
function loader(src, map) {
const options = getOptions(this);
validate(schema, options, {
name: "Loader Name",
baseDataPath: "options",
});
}
export default loader;
Plugin
import { validate } from "schema-utils";
import schema from "path/to/schema.json";
class Plugin {
constructor(options) {
validate(schema, options, {
name: "Plugin Name",
baseDataPath: "options",
});
this.options = options;
}
apply(compiler) {
}
}
export default Plugin;
Allow to disable and enable validation (the validate
function do nothing)
This can be useful when you don't want to do validation for production
builds.
import { disableValidation, enableValidation, validate } from "schema-utils";
disableValidation();
validate(schema, options);
enableValidation();
validate(schema, options);
const need = needValidate();
console.log(need);
Also you can enable/disable validation using the process.env.SKIP_VALIDATION
env variable.
Supported values (case insensitive):
yes
/y
/true
/1
/on
no
/n
/false
/0
/off
Contributing
Please take a moment to read our contributing guidelines if you haven't yet done so.
CONTRIBUTING
License
MIT