SemVer Parser

What is Semantic Versioning?

Semantic Versioning (SemVer) is a versioning convention that assigns meaning to each number in a version string. Instead of arbitrary version numbers, SemVer encodes the nature of changes directly into the version — making it possible for both humans and machines to understand what changed between two releases.

The core idea is captured in a single sentence from the spec: “Given a version number MAJOR.MINOR.PATCH, increment the MAJOR version when you make incompatible API changes, the MINOR version when you add functionality in a backward-compatible manner, and the PATCH version when you make backward-compatible bug fixes.”

SemVer is the foundation of modern dependency management. Package managers like npm, Cargo, Composer, and NuGet rely on SemVer to automatically resolve compatible versions, preventing applications from accidentally pulling in breaking changes while still receiving bug fixes and new features.

The Three Numbers Explained

Every semantic version consists of three non-negative integers separated by dots:

MAJOR.MINOR.PATCH

Component	When to Increment	Example
MAJOR	Breaking changes to the public API	1.0.0 to 2.0.0 — renamed function, removed endpoint
MINOR	New features that are backward-compatible	1.0.0 to 1.1.0 — added new API endpoint
PATCH	Bug fixes that are backward-compatible	1.0.0 to 1.0.1 — fixed calculation error

When you increment a higher-priority number, all lower numbers reset to zero. Bumping MAJOR resets MINOR and PATCH. Bumping MINOR resets PATCH only.

Before	Change Type	After	Explanation
1.4.2	Breaking change	2.0.0	MAJOR bump, MINOR and PATCH reset
1.4.2	New feature	1.5.0	MINOR bump, PATCH resets
1.4.2	Bug fix	1.4.3	PATCH bump only

Pre-release and Build Metadata

SemVer supports two optional extensions appended to the MAJOR.MINOR.PATCH core:

Pre-release Identifiers

A pre-release version is denoted by appending a hyphen and a series of dot-separated identifiers after the PATCH version:

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

Pre-release versions indicate that the version is unstable and may not satisfy the compatibility requirements of the normal version. They have lower precedence than the associated normal version: 1.0.0-alpha < 1.0.0.

Pre-release identifiers are compared left to right. Numeric identifiers are compared as integers; alphanumeric identifiers are compared lexically. Numeric identifiers always have lower precedence than alphanumeric ones. This means 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-rc.1.

Build Metadata

Build metadata is appended using a plus sign after the version (or after the pre-release tag if present):

1.0.0+20240315
1.0.0-beta.1+build.456

Build metadata is completely ignored when determining version precedence. Two versions that differ only in build metadata are considered equal: 1.0.0+build.1 == 1.0.0+build.2. Build metadata is typically used to record information like commit hashes, build timestamps, or CI pipeline identifiers.

Version 0.x.y — Initial Development

The SemVer specification carves out a special exception for versions with a MAJOR of 0:

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

This means that during the 0.x.y phase, there are no guarantees. A bump from 0.2.3 to 0.3.0 might include breaking changes. A bump from 0.2.3 to 0.2.4 might introduce new features. The normal rules only take full effect once the project reaches 1.0.0.

This distinction is important for dependency management. Package managers treat 0.x.y ranges more cautiously. For example, in npm, ^0.2.3 resolves to >=0.2.3 <0.3.0 rather than >=0.2.3 <1.0.0 — the caret operator becomes stricter to account for the instability of pre-1.0 releases.

Version Precedence Rules

SemVer defines a clear ordering for versions:

1. MAJOR, MINOR, PATCH are compared numerically from left to right: 1.9.0 < 1.10.0 < 2.0.0
2. Pre-release versions have lower precedence than the normal version: 1.0.0-alpha < 1.0.0
3. Pre-release identifiers are compared left to right: numeric < alphanumeric, numeric by value, alphanumeric lexically
4. Build metadata is ignored entirely for precedence

This ordering enables package managers to sort, compare, and select the most appropriate version automatically.

Common Use Cases

• npm / Node.js: Every npm package uses SemVer. The package.json dependencies field expects SemVer ranges (^1.2.3, ~1.2.3)
• Rust / Cargo: Cargo strictly enforces SemVer for all crates published to crates.io
• PHP / Composer: Composer uses SemVer for PHP package dependency resolution
• API versioning: REST and GraphQL APIs use MAJOR versions (v1, v2) to signal breaking changes in endpoints
• CLI tools: Command-line tools follow SemVer to communicate backward compatibility of flags, outputs, and behavior
• Libraries and frameworks: React, Vue, Angular, Django, Rails — all use SemVer to guide upgrade decisions