{"id":20538,"library":"schema-utils","title":"schema-utils","description":"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.","status":"active","version":"4.3.3","language":"javascript","source_language":"en","source_url":"https://github.com/webpack/schema-utils","tags":["javascript","webpack","typescript"],"install":[{"cmd":"npm install schema-utils","lang":"bash","label":"npm"},{"cmd":"yarn add schema-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add schema-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used as the underlying JSON Schema validator","package":"ajv","optional":false},{"reason":"Provides additional validation keywords (e.g., typeof, instanceof)","package":"ajv-keywords","optional":false}],"imports":[{"note":"ESM import is recommended. CJS require still works but may lack TypeScript types in some bundler setups.","wrong":"const { validate } = require('schema-utils')","symbol":"validate","correct":"import { validate } from 'schema-utils'"},{"note":"Available since v3. Use for instanceof checks or custom error handling.","wrong":"const ValidationError = require('schema-utils').ValidationError","symbol":"ValidationError","correct":"import { ValidationError } from 'schema-utils'"},{"note":"Schema is a TypeScript type, not a runtime value. Use type import to avoid side effects.","wrong":"import { Schema } from 'schema-utils'","symbol":"Schema","correct":"import type { Schema } from 'schema-utils'"}],"quickstart":{"code":"import { validate } from 'schema-utils';\nimport schema from './schema.json' with { type: 'json' };\n\nconst options = { mode: 'production', devtool: 'source-map' };\nconst configuration = { name: 'MyPlugin', baseDataPath: 'options' };\n\ntry {\n  validate(schema, options, configuration);\n  console.log('Options are valid');\n} catch (error) {\n  if (error instanceof TypeError && error.name === 'ValidationError') {\n    console.error('Validation failed:', error.message);\n  }\n}","lang":"typescript","description":"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."},"warnings":[{"fix":"Use 'import schema from './schema.json' with { type: 'json' }'.","message":"JSON import assertions syntax changed: import schema from './schema.json' assert { type: 'json' } no longer works; use 'with' keyword instead.","severity":"breaking","affected_versions":">= node 20.10.0 || >= node 21.0.0"},{"fix":"Import these types from 'ajv' directly instead.","message":"Exporting 'ValidateFunction', 'SchemaObject', 'ErrorObject' types is deprecated in v4. These types are now re-exported from ajv directly.","severity":"deprecated","affected_versions":"4.x"},{"fix":"Upgrade to v4.2.0+ or v3.3.0+ to use enable()/disable().","message":"Disabling validation globally via enable()/disable() is only available in v4.2.0+ and v3.3.0+.","severity":"gotcha","affected_versions":"< 4.2.0 || < 3.3.0"},{"fix":"Change schema to use 'type: \"object\"' and add 'items' for array members, or use 'type: \"array\"' for array schemas.","message":"Arrays as the object type in schema are disallowed since v4.3.0. Previously they were silently accepted.","severity":"breaking","affected_versions":">= 4.3.0"},{"fix":"Switch to ESM import syntax or use 'createRequire' from 'module' to ensure proper exports.","message":"When using CJS require, the returned object may not have the 'ValidationError' constructor due to bundler optimizations.","severity":"gotcha","affected_versions":">= 4.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use named import: import { validate } from 'schema-utils'.","cause":"Using default import (import validate from 'schema-utils') instead of named import.","error":"TypeError: Cannot read properties of undefined (reading 'validate')"},{"fix":"Add configuration object with name and optionally baseDataPath: validate(schema, options, { name: 'MyPlugin', baseDataPath: 'options' }).","cause":"Configuration object passed to validate() is missing the 'name' or 'baseDataPath' property, causing confusing error messages.","error":"Invalid configuration object. Object has been initialised using a configuration object that does not match the API schema."},{"fix":"Run 'npm install schema-utils'.","cause":"Missing dependency schema-utils in package.json.","error":"Module not found: Can't resolve 'schema-utils' in ..."},{"fix":"Either remove the unexpected property from options or update the schema to allow it.","cause":"The schema has additionalProperties: false and the options object contains a property not in the schema.","error":"Schema validation failed: data should NOT have additional properties"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}