SemVer Validator

SemVer 2.0.0: a contract between library authors and consumers

Semantic Versioning, codified at semver.org by Tom Preston-Werner (co-founder of GitHub), turns a version string into a machine-readable contract. The current revision is SemVer 2.0.0, and almost every modern package registry — npm, Cargo, RubyGems, Packagist, Composer, NuGet, Go modules — leans on it to compute dependency graphs.

The promise is simple: by reading the digits alone, a consumer can predict whether an upgrade is safe. The validator on this page checks that a string conforms to the full grammar published in the specification — including the optional pre-release identifier and the optional build metadata.

The MAJOR.MINOR.PATCH triplet

A release version is exactly three non-negative integers separated by dots, with no leading zeros: 1.2.3, 0.4.17, 10.0.0. The increment rules are strict:

• MAJOR — bumped on a backward-incompatible (breaking) change to the public API.
• MINOR — bumped when backward-compatible functionality is added.
• PATCH — bumped on backward-compatible bug fixes only.

Bumping a higher component resets the lower ones to zero: 1.4.7 -> 2.0.0, not 2.4.7. Internal refactors that do not affect the public surface stay on PATCH.

Pre-release identifiers and build metadata

A pre-release is appended with a hyphen and dot-separated identifiers made of ASCII letters, digits and hyphens: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1. Pre-releases sort lower than the normal version, and identifier order matters — alpha < alpha.1 < beta < rc.1 < 1.0.0.

Build metadata follows a plus sign and is ignored for precedence: 1.0.0+20240501, 1.0.0-beta+exp.sha.5114f85. Two builds that differ only in metadata are considered the same release for dependency resolution.

1.0.0-alpha    < 1.0.0-alpha.1
1.0.0-alpha.1  < 1.0.0-beta
1.0.0-beta     < 1.0.0-rc.1
1.0.0-rc.1     < 1.0.0
1.0.0          == 1.0.0+build.42

The 0.x.x phase: anything can change

During initial development with a MAJOR of 0 the API is explicitly unstable: the spec says "anything MAY change at any time". Many libraries linger here for years to signal experimental status. The first stable release is 1.0.0, and it should be cut once the public API is considered ready for production use.

A common antipattern is jumping straight from 0.9.x to 2.0.0 without ever publishing 1.0.0. Some projects also adopt joke schemes such as "0ver" (sentimentalversioning.org) where the major never reaches 1 — fun, but useless for automated dependency resolvers.

npm range syntax: caret, tilde and explicit ranges

SemVer is most visible inside package.json. The node-semver library implements parsing, comparison and range satisfaction. The two most common range prefixes are:

• ^1.2.3 (caret) — compatible release: >=1.2.3 <2.0.0. Permits MINOR and PATCH bumps.
• ~1.2.3 (tilde) — close release: >=1.2.3 <1.3.0. Permits only PATCH bumps.
• >=1.0.0 <2.0.0 — explicit range, identical to caret for major > 0.
• 1.2.x or 1.2.* — equivalent to tilde.

For caret with MAJOR 0 the behavior changes: ^0.2.3 resolves to >=0.2.3 <0.3.0 because pre-1.0 minors can break. The lockfile (package-lock.json, yarn.lock, pnpm-lock.yaml) pins the resolved versions so that npm ci is fully reproducible. Yarn Plug'n'Play (PnP) pushes determinism further by eliminating node_modules.

Beyond npm: GitHub releases, Docker tags and API versions

SemVer leaks into many other surfaces:

• Git tags — convention v1.2.3 on GitHub releases (the leading v is not part of SemVer itself).
• Docker tags — node:20.11.0, with rolling aliases node:20 and node:latest.
• HTTP APIs — usually only MAJOR is exposed via URL prefix (/v1/, /v2/) or a custom header. Internally the team can still track MINOR/PATCH on the implementation.
• Conventional Commits — tools such as semantic-release and release-please read commit messages (feat:, fix:, BREAKING CHANGE:) to compute the next SemVer automatically.

A different scheme entirely is CalVer (calendar versioning), used by Ubuntu (24.04), pip and Black. CalVer trades the breaking-change signal for predictable release cadence — pick SemVer for libraries and CalVer for time-based products.

FAQ

Is a 0.x.x release considered stable?

No. The spec reserves MAJOR 0 for initial development and explicitly allows breaking changes on every MINOR bump. Cut 1.0.0 once the public API is locked in.

When should I bump from 0.x to 1.0?

When the API is being used in production and you commit to the stability guarantees of SemVer. Many projects do it when the documentation is complete and at least one external dependent exists.

How are pre-release identifiers ordered?

Compare identifier by identifier from left to right. Numeric identifiers compare numerically; alphanumeric ones compare lexicographically; numeric is always lower than alphanumeric of the same position; fewer identifiers is lower than more identifiers if the prefix matches.

Does build metadata affect precedence?

No. 1.0.0+build.1 and 1.0.0+build.2 are equivalent for dependency resolution. Use metadata only for traceability (commit SHA, CI run id, etc.).

Caret or tilde — which is safer?

Tilde is more conservative (PATCH only) and minimises surprise. Caret is more permissive and assumes the maintainer respects SemVer. For application code with a lockfile, caret is the npm default and usually fine.