schema-utils

4.3.3 verified Sat Apr 25 auth: no javascript

Schema validation utility for webpack loaders, plugins, and other configuration objects. Version 4.3.3 is the latest stable release, actively maintained alongside webpack. It provides a validate() function that checks options against a JSON Schema, with clear error messages including the plugin/loader name and data path. Differentiates from generic validators like ajv by being tailored for webpack's configuration context, supporting post-formatting of errors and a configuration object for naming. Ships TypeScript types and has both ESM and CJS builds. Primarily used internally by webpack but also directly by custom loaders and plugins.

Common errors

error TypeError: Cannot read properties of undefined (reading 'validate') ↓

cause Using default import (import validate from 'schema-utils') instead of named import.

fix

Use named import: import { validate } from 'schema-utils'.

error Invalid configuration object. Object has been initialised using a configuration object that does not match the API schema. ↓

cause Configuration object passed to validate() is missing the 'name' or 'baseDataPath' property, causing confusing error messages.

fix

Add configuration object with name and optionally baseDataPath: validate(schema, options, { name: 'MyPlugin', baseDataPath: 'options' }).

error Module not found: Can't resolve 'schema-utils' in ... ↓

cause Missing dependency schema-utils in package.json.

fix

Run 'npm install schema-utils'.

error Schema validation failed: data should NOT have additional properties ↓

cause The schema has additionalProperties: false and the options object contains a property not in the schema.

fix

Either remove the unexpected property from options or update the schema to allow it.

Warnings

breaking JSON import assertions syntax changed: import schema from './schema.json' assert { type: 'json' } no longer works; use 'with' keyword instead. ↓

fix Use 'import schema from './schema.json' with { type: 'json' }'.

deprecated Exporting 'ValidateFunction', 'SchemaObject', 'ErrorObject' types is deprecated in v4. These types are now re-exported from ajv directly. ↓

fix Import these types from 'ajv' directly instead.

gotcha Disabling validation globally via enable()/disable() is only available in v4.2.0+ and v3.3.0+. ↓

fix Upgrade to v4.2.0+ or v3.3.0+ to use enable()/disable().

breaking Arrays as the object type in schema are disallowed since v4.3.0. Previously they were silently accepted. ↓

fix Change schema to use 'type: "object"' and add 'items' for array members, or use 'type: "array"' for array schemas.

gotcha When using CJS require, the returned object may not have the 'ValidationError' constructor due to bundler optimizations. ↓

fix Switch to ESM import syntax or use 'createRequire' from 'module' to ensure proper exports.

Install

npm install schema-utils

yarn add schema-utils

pnpm add schema-utils

Imports

validate
wrong
```
const { validate } = require('schema-utils')
```
correct
```
import { validate } from 'schema-utils'
```
ESM import is recommended. CJS require still works but may lack TypeScript types in some bundler setups.

ValidationError

wrong

const ValidationError = require('schema-utils').ValidationError

correct

import { ValidationError } from 'schema-utils'

Available since v3. Use for instanceof checks or custom error handling.

Schema
wrong
```
import { Schema } from 'schema-utils'
```
correct
```
import type { Schema } from 'schema-utils'
```
Schema is a TypeScript type, not a runtime value. Use type import to avoid side effects.

Quickstart

Demonstrates validating options against a JSON schema with error handling, using a custom name and base data path. The import uses JSON with assertion for ES modules.

import { validate } from 'schema-utils';
import schema from './schema.json' with { type: 'json' };

const options = { mode: 'production', devtool: 'source-map' };
const configuration = { name: 'MyPlugin', baseDataPath: 'options' };

try {
  validate(schema, options, configuration);
  console.log('Options are valid');
} catch (error) {
  if (error instanceof TypeError && error.name === 'ValidationError') {
    console.error('Validation failed:', error.message);
  }
}