What do MAJOR, MINOR, and PATCH mean?

MAJOR is incremented for incompatible API changes, MINOR for backward-compatible new features, and PATCH for backward-compatible bug fixes. The format is always three non-negative integers without leading zeros, written MAJOR.MINOR.PATCH.

How does pre-release precedence work?

A version with a pre-release tag has lower precedence than the same version without one, so 1.0.0-rc.1 is less than 1.0.0. Pre-release identifiers are compared field by field: numeric ones numerically, alphanumeric ones in ASCII order, and a larger set of fields wins if all earlier fields are equal.

What does the caret operator allow?

The caret (^) allows changes that do not modify the left-most non-zero version component. ^1.2.3 permits >=1.2.3 =0.2.3 <0.3.0 because for 0.x releases the minor is treated as the compatibility boundary.

Does build metadata affect precedence?

No. Build metadata is the part after a plus sign, such as 1.0.0+20130313144700. It is ignored entirely when determining version precedence, so two versions differing only in build metadata are considered equal in ordering.

Are leading zeros allowed in version numbers?

No. Numeric identifiers in the core version and in pre-release tags must not include leading zeros, so 1.01.0 and 1.0.0-alpha.01 are both invalid. This keeps numeric comparison unambiguous.

What is the Semantic Versioning Reference?

Interactive Semantic Versioning 2.0 reference and parser. Validate MAJOR.MINOR.PATCH versions, inspect pre-release and build metadata, compare two versions by precedence, and learn npm range operators like ^, ~, and *. It runs free in your browser on Gera Tools, with nothing uploaded.

Semantic Versioning Reference

Name: Semantic Versioning Reference
Creator: Gera Tools
License: https://creativecommons.org/licenses/by/4.0/

Get one useful tool a week

Like this tool? Enter your email and we'll send you one genuinely useful Gera tool a week — plus a link to come back to this one. No spam, one-click unsubscribe any time.

Semantic Versioning is a contract between a package and everyone who depends on it. The version number itself communicates whether an upgrade is safe. This tool parses a version against the SemVer 2.0 grammar, compares two versions by the official precedence rules, and documents the npm range operators you use in package.json.

How it works

A valid SemVer string is MAJOR.MINOR.PATCH, optionally followed by a pre-release tag (-alpha.1) and build metadata (+build.5). The full grammar is:

1.4.2
1.4.2-beta.3
1.4.2-rc.1+exp.sha.5114f85

The parser validates that all three core numbers are non-negative integers with no leading zeros, then splits any pre-release and build sections.

Precedence is determined by comparing major, minor, and patch numerically. If those are equal, a version with a pre-release tag ranks below one without. Pre-release identifiers are then compared left to right: numeric identifiers compare numerically, alphanumeric ones compare in ASCII sort order, numeric always ranks lower than alphanumeric, and if one runs out of fields first it ranks lower. Build metadata is never compared.

Range operators and tips

The npm operators control which versions a dependency range accepts:

^1.2.3 — compatible with 1.2.3, allows >=1.2.3 <2.0.0.
~1.2.3 — allows patch-level changes, >=1.2.3 <1.3.0.
1.2.x / 1.2.* — any patch within 1.2.
>=1.2.0 <2.0.0 — explicit comparator range.

A good habit: publish 0.x releases while the API is unstable, because under ^ and ~ the 0.x rules tighten the allowed range automatically. Once you ship 1.0.0, every breaking change must bump the major number.

Pre-release precedence in depth

This is the part of SemVer that trips people up most often. Consider these versions in ascending precedence order:

1.0.0-alpha
1.0.0-alpha.1
1.0.0-alpha.beta
1.0.0-beta
1.0.0-beta.2
1.0.0-beta.11
1.0.0-rc.1
1.0.0

Notice beta.11 comes after beta.2 because numeric identifiers compare numerically (11 > 2), not lexicographically (which would make “11” sort before “2”). Also notice alpha.beta sorts after alpha.1 because alphanumeric identifiers always rank higher than numeric ones in the same position.

Common validation errors

Leading zeros — 1.01.0 is invalid. A numeric identifier must not have a leading zero because it could be read as octal notation. 1.1.0 is the correct form.

Negative numbers — version numbers are non-negative integers; -1.0.0 is not valid.

Empty fields — 1..0 with a missing minor is not valid; all three fields are required.

Invalid pre-release — 1.0.0- with a trailing hyphen and no identifier is invalid. Pre-release identifiers must be at least one character.

Practical workflow

Use the parser here to spot-check a version string if your tooling behaves unexpectedly. For example, if npm install refuses to satisfy a range you think should match, paste both the range pattern and the candidate version to confirm they behave as the SemVer spec requires. The comparison view also makes it easy to confirm that two versions sort in the expected order before you tag a release.