Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
validate
✓ import { validate } from 'schema-utils'
✗ const { validate } = require('schema-utils')
ESM import is recommended. CJS require still works but may lack TypeScript types in some bundler setups.
ValidationError
✓ import { ValidationError } from 'schema-utils'
✗ const ValidationError = require('schema-utils').ValidationError
Available since v3. Use for instanceof checks or custom error handling.
Schema
✓ import type { Schema } from 'schema-utils'
✗ import { Schema } from 'schema-utils'
Schema is a TypeScript type, not a runtime value. Use type import to avoid side effects.
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);
}
}
Debug
Known issues
breakingJSON import assertions syntax changed: import schema from './schema.json' assert { type: 'json' } no longer works; use 'with' keyword instead.fixUse 'import schema from './schema.json' with { type: 'json' }'. affects: >= node 20.10.0 || >= node 21.0.0
deprecatedExporting 'ValidateFunction', 'SchemaObject', 'ErrorObject' types is deprecated in v4. These types are now re-exported from ajv directly.fixImport these types from 'ajv' directly instead.
affects: 4.x
gotchaDisabling validation globally via enable()/disable() is only available in v4.2.0+ and v3.3.0+.fixUpgrade to v4.2.0+ or v3.3.0+ to use enable()/disable().
affects: < 4.2.0 || < 3.3.0
breakingArrays as the object type in schema are disallowed since v4.3.0. Previously they were silently accepted.fixChange schema to use 'type: "object"' and add 'items' for array members, or use 'type: "array"' for array schemas.
affects: >= 4.3.0
gotchaWhen using CJS require, the returned object may not have the 'ValidationError' constructor due to bundler optimizations.fixSwitch to ESM import syntax or use 'createRequire' from 'module' to ensure proper exports.
affects: >= 4.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'validate')
Using default import (import validate from 'schema-utils') instead of named import.
fixUse named import: import { validate } from 'schema-utils'. Invalid configuration object. Object has been initialised using a configuration object that does not match the API schema.
Configuration object passed to validate() is missing the 'name' or 'baseDataPath' property, causing confusing error messages.
fixAdd configuration object with name and optionally baseDataPath: validate(schema, options, { name: 'MyPlugin', baseDataPath: 'options' }). Module not found: Can't resolve 'schema-utils' in ...
Missing dependency schema-utils in package.json.
fixRun 'npm install schema-utils'.
Schema validation failed: data should NOT have additional properties
The schema has additionalProperties: false and the options object contains a property not in the schema.
fixEither remove the unexpected property from options or update the schema to allow it.
Audit
Dependencies
ajvrequiredUsed as the underlying JSON Schema validator
ajv-keywordsrequiredProvides additional validation keywords (e.g., typeof, instanceof)