Terms

Glossary

The words in the explanations and the response, each with a short definition and a link to where it is used.

Settings

Term	Meaning
Age gate	The minimum age of a version, `minAgeDays`. Younger versions are not candidates. See why wait.
Step	How far a version may move from the one in your file, `maxBump`: `patch`, `minor` or `major`. Measured from the lower bound of your range. See step size.
Focus	The packages you name for one run. Only they move, together with the neighbours they need. See focus.
`ripedeps` entry	The object in package.json that keeps `minAgeDays` and `maxBump`. See Configuration.

Term	Meaning
Root	A package listed in `dependencies`, `devDependencies` or `optionalDependencies` of your file.
Floor	The lower bound of a range: `1.2.0` in `^1.2.0`.
Baseline	What your project resolves to today: the highest stable version that satisfies your range. It always stays a candidate, so nothing moves backwards.
Candidate	A version that may be chosen: stable, not deprecated, within the step, old enough, and compatible with your `engines.node`. See candidate versions.
Best version	`bestVersion`: the best candidate of a package. When it differs from the chosen version, the explanation says what stood in the way.
Lag	How far a chosen version is behind the best candidate. A major gap counts 10000, a minor gap 100 and a differing patch 1. See ranking.

Term	Meaning
Constraint	A rule between two of your packages that holds when the chosen version of one satisfies the range another asks for. See constraints.
Peer	A constraint from a `peerDependencies` entry, for example a framework asking for `react ^19`.
Aligned dependency	A constraint from a `dependencies` entry that points to another root of yours, so the same package does not end up in two versions.
Movable set	The packages allowed to move in a run: all of them, or with a focus, the focused ones and the neighbours their candidates refer to.
Exact	`meta.exact`: `true` when the solver proved its answer is the best one. When its search budget ran out, it is `false` and the best answer found is returned. See the solver.

The decision for each package, the status in the response. See decisions.

Status	Meaning
`upgrade`	The range moves up to the chosen version.
`held`	A newer version exists but is not taken: too young, too big a step, needs a newer Node, or it would break a peer or an aligned dependency.
`current`	Already the newest version that qualifies.
`outside-focus`	Not part of the focus, left as it is.
`skipped`	Not processable. `skipReason` says why: `non-semver-specifier`, `open-ended`, `complex-range`, `unsupported-range`, `prerelease`, `invalid-value`, `unknown-package` or `lookup-failed`.

Why a better version was not taken, reasons[].kind in the response.

Kind	Meaning
`age-gate`	The newest stable version is younger than the gate. Its age is given.
`engines`	The version needs a newer Node than your `engines.node` allows, or, for `@types/node`, it follows `engines.node`.
`level-limit`	A higher version exists, but your step excludes it.
`peer`	The version would break a peer constraint.
`dependency`	The version would break an aligned dependency.
`pulled-in`	The package can move because a focused package needs it.

Field	Meaning
`diff`	A unified diff of package.json that `patch -p1` applies.
`updatedPackageJson`	The complete new file.
`explanation`	One sentence per package: what happened and why. Built from templates, never by a model. See explanations.
`warnings`	Things you should know: duplicates, unavoidable constraint violations with a hint, unknown keys in the `ripedeps` entry.
`notes`	Changes to the output that are not upgrades, for example that the entry was added.
`meta`	The settings used and where each came from, the input, `exact` and `stale`.
`stale`	`meta.stale`: expired package data was served because the registry was briefly unavailable.

The full reference with an example of every field is on the API page. More questions? See the FAQ.