The custom-validation API loads a JavaScript validator file and returns normalized Problems.

Options

Option Type Required Constraint Aliases
customValidatorPath string Yes Existing .js or .cjs file inside the current working directory path, customPath
customCatalogPath string No Existing .json file inside the current working directory catalogPath

The API rejects paths that contain traversal segments. Resolved paths must remain inside the current working directory.

runCustomValidation(documentValue, options)

This asynchronous function runs the validator in a subprocess. The worker has a 5-second execution timeout and bounded output.

JavaScript
const { runCustomValidation } = require("workspec");

const problems = await runCustomValidation(startingState, {
  customValidatorPath: "./validators/project.js"
});

The Promise resolves to WorkSpecProblem[]. Setup, worker, timeout, and invalid-output failures reject the Promise.

runCustomValidationInProcess(documentValue, options)

This asynchronous function runs the same validation contract in the caller's process. Await its WorkSpecProblem[] result.

Use the subprocess API when the caller needs the package's custom-validation isolation boundary.

See Problems and diagnostics for normalized result fields.