Specification · 1.0.0

Software versions are a
communication mechanism.

Semantic Versions is an open specification for how version numbers are
assigned, incremented, grouped, compared and matched.
A spiritual successor to Semantic Versioning 2.0.0-rc.1.

anatomy of a version

npm:react@1.2.3-beta.4+build.7
# source:name @ major.minor.patch-prerelease+build

Read the spec Try the range selector

Why a new spec

Versioning should mirror how software actually changes.

Semantic Versioning 2.0.0 is more than a decade old, has not meaningfully changed in that time, and has no realistic path to a 3.0. The way we ship software has moved on. JavaScript avoided the first circle of dependency hell only because tooling quietly bolted sets, ranges and comparators onto a spec that never defined them. We have since landed in a deeper circle, where package managers read the same version differently and resolve to different graphs.

A specification is a language, and it is only as good as the definitions it contains. Software changes over time and sometimes breaks; that is natural, and necessary for growth. A versioning spec exists to codify the signals that communicate change, so it should codify the ones we actually use.

What changed

Corrected definitions, restored meaning, formal grammars.

Patch, corrected

A patch is a fix for behaviour that was never intended, not a promise of backward compatibility (which is practically impossible to guarantee). The definition is amended so a fix stays a fix.

Builds get their precedence back

2.0.0-rc.2 turned builds into inert "build metadata," making every build of a version equivalent. Two artifacts with different hashes or architectures are distinct software, so builds order again.

Sets & subsets

Precedence alone can't describe a collection of versions. This spec defines ordered, unordered, normal, prerelease and build sets: the vocabulary you need to manage more than one version at a time.

Ranges & comparators

Comparators (>=1.2.7), comparator sets, hyphen ranges, x-ranges, tilde and caret. The grammar tools already ship, defined so they desugar to primitive comparators in one deterministic way.

Approximate ranges (`~>`)

The pessimistic operator, borrowed from the Ruby world, is defined explicitly rather than left to each tool's imagination.

A reference implementation & BNF

Backus–Naur grammars for versions, ranges and comparators, plus a parser you can read, so anyone can build a compliant library.

SPEC

The specification

The full ruleset: versions, sets, ranges, comparators and precedence.

Read →

PROPOSAL

Semantic Versioning 3.0.0

The case for making this spec the next version of Semantic Versioning, and why it stands on its own regardless.

See the case →

TRY IT

Range selector

Test what matches what against the range grammar, entirely in your browser.

Open →

GRAMMAR

BNF grammars

Formal Backus–Naur forms, ready to build a library from.

View →

HISTORY

History

How builds were introduced, and how a later change made them meaningless.

Trace →

EXTENSION

Dependency Locks

Pinning a resolved subgraph inside a source-qualified version, built on this spec.

Explore →