Upgrade Validator
Developmentupgrade-validatorUpgrade Validator is an Agent Skill for development published in the express-validator/express-validator repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Upgrades the npm `validator` dependency and syncs express-validator chain types, implementations, options, and `declarations/validator.d.ts` with validator.js releases. Express-validator intentionally pins `validator` to patch-only semver (see PR
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/express-validator/express-validator/blob/HEAD/.agents/skills/upgrade-validator/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/upgrade-validator, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
upgrade-validator
Policy: why upgrades are manual
This project does not float on arbitrary new minor lines of validatorjs/validator.js. As described in express-validator#1253, the validator dependency is pinned to patch (e.g. ~x.y.z) so a new minor from upstream cannot be pulled in implicitly and surface mistaken or unexpected breaking changes. Bumping validator is a deliberate maintainers’ task: run this workflow, sync types and chain APIs, test, and ship.
After npm install, keep package.json consistent with that policy (typically ~<resolved-version>, not a loose ^ on the major/minor line unless the project explicitly changes policy).
Before you start
- Record the previous
validatorversion frompackage.json(and confirm after upgrade frompackage.json/ lockfile). - The source of truth for what changed is validatorjs/validator.js. Use a tag range compare (e.g.
v<old>...v<new>) to see commits and the diff between versions.
1. Upgrade the package
From the repo root, install the latest validator in-range and persist it to package.json / the lockfile:
npm install validator@latest
If npm rewrites the range to ^ and the project uses patch-only pinning per #1253, change the dependency to ~<version> to match the previous convention.
2. Map upstream changes to this codebase
For each new validator, sanitizer, or option type introduced between the old and new version (use the GitHub compare / changelog, not only commit titles):
New validator (check API)
src/chain/validators.ts: under// validator's validators, add the new method signature in alphabetical order with the rest. Follow existing JSDoc style for adjacent methods.src/chain/validators-impl.ts: under// Standard validators, add the implementation in alphabetical order, delegating withaddStandardValidation(validator.<name>, ...)the same way sibling methods do. If upstream uses custom logic (see e.g.isAlpha,toArray-style), match the existing pattern in that file.
New sanitizer
src/chain/sanitizers.ts: under// validator's sanitizers, add the method in alphabetical order.src/chain/sanitizers-impl.ts: under// Standard sanitizers, add the implementation in alphabetical order (addStandardSanitizationvscustomSanitizeras appropriate).
New options / types
src/options.ts: add or extend types only when the new value is:- enum-like (e.g. a new locale, a new UUID version constant), or
- an object (e.g.
{ min, max }, or other structured options).
- Skip
options.tsfor parameters that are only a plainstringornumberwith no new shared option shape—use inline types on the chain method if needed, consistent with nearby code.
Everything else
- Upstream internal or non–type-surface changes that do not add or change validator/sanitizer signatures need no express-validator edits beyond the version bump and declaration sync (if any).
3. Declarations
- Update
declarations/validator.d.ts: newexport functionentries must stay in alphabetical order and match the installedvalidatorcall signatures. Reuseimport('../src/options').<Type>for option types the same way existing declarations do.
4. Verify
From the repo root:
npm test
npm run lint
npm run docs:regenerate-api
Fix any failures before finishing.
Quick reference — section markers
| File | Section comment |
|---|---|
src/chain/validators.ts | // validator's validators |
src/chain/validators-impl.ts | // Standard validators |
src/chain/sanitizers.ts | // validator's sanitizers |
src/chain/sanitizers-impl.ts | // Standard sanitizers |