FAQ

Common questions, answered.

The reasoning behind the rules: why some things changed from Semantic Versioning 2.0.0, why others deliberately didn't, and how the spec fits alongside the rest of the ecosystem. The normative text is the specification.

Common misconceptions

Aren’t the versions in my package.json “semver”?

Not quite. What you write under dependencies is a range (^1.2.0, ~1.4, >=2 <3, 1.x), and Semantic Versioning 2.0.0 does not define ranges at all. It specifies what a version string looks like and how two versions order; carets, tildes, x-ranges, hyphen ranges and || appear nowhere in it. npm’s documentation sends you to the semver package’s README for range syntax, and that README carries its own grammar. So the language millions of manifests are written in is defined by one library’s documentation, not by the spec it is named after.

The same goes for behaviour people assume is “semver”. That ^1.0.0 never matches 2.0.0-rc.1 is a node-semver rule: a pre-release only satisfies a range when a comparator on the same major.minor.patch carries a pre-release too. Reasonable, widely copied, and nowhere in the spec. And a dependency field need not hold a version or range at all: npm also accepts tarball and git URLs, GitHub shorthands, dist-tags like latest, local paths and npm: aliases.

Semantic Versions writes these rules down as part of the specification, with a grammar and a shared conformance suite, so a range means the same thing in every tool that implements it.

Isn’t semver.org an official standard?

It is a widely adopted document rather than a standard in the formal sense. Semantic Versioning was written by Tom Preston-Werner, announced in December 2009, and is published on a website under CC BY 3.0. It has not gone through a standards body such as the IETF, ECMA or ISO. Version 2.0.0 was released in June 2013, and it is still the current version.

It does have stewards. In 2019 its long-time maintainer handed it to a group of maintainers from package managers that use it (npm, Bundler, Cargo, Composer, NuGet, CocoaPods and others), who adopted an RFC process. Under that process a change counts as adopted only once the maintainers approve it and a majority of their implementations ship it, and changes that would significantly break any of those communities are ruled out. That makes the spec stable, which matters, but it also means the definitions tools needed and invented for themselves (ranges, pre-release matching, what a build is for) were never brought into it.

Ranges are the clearest example. The range syntax most people know comes from node-semver, which Isaac Z. Schlueter wrote for npm in 2011. In 2020 he proposed adding a ranges specification to Semantic Versioning (semver/semver#584). Maintainers of other package managers pointed out where their tools differ and that aligning them would break existing constraints; the proposal is still open. Much of the range grammar in Semantic Versions descends from that work, extended with pre-release and build channels, wildcards and contexts. The history has the timeline.

Semantic Versions does not try to replace that process. It is a separate, versioned specification that keeps every Semantic Versioning 2.0.0 version valid and adds the missing parts in the open, at vltpkg/semantic-versions.

Doesn’t every package manager read versions the same way?

They agree on the shape of a version and disagree on almost everything around it. A few examples, each from the tool’s own documentation:

  • A bare version. In npm, 1.2.3 means exactly that version. In Cargo, 1.2.3 is a caret requirement and means >=1.2.3, <2.0.0.
  • The v prefix. Semantic Versioning 2.0.0 says v1.2.3 is not a semantic version. Go modules require it (v1.2.3), while node-semver strips it and accepts the rest.
  • Builds. Semantic Versioning 2.0.0 says build metadata MUST be ignored for precedence, so 1.0.0+linux and 1.0.0+windows are “equal”. Go ignores the suffix when comparing versions, and node-semver drops it when it normalizes one. Two different artifacts end up indistinguishable to the resolver.
  • Range syntax. npm separates comparators with spaces and alternatives with ||; Cargo separates comparators with commas and has no ||; Python’s PEP 440 uses ~= and ==1.4.*; Composer and RubyGems each have their own.

Each choice is defensible on its own. Together they mean that “semver” names a family of dialects, and that the same version or range can resolve differently depending on which tool reads it. That is the gap Semantic Versions closes: one definition of versions, precedence (builds included), sets, ranges and comparators, with implementations in eight languages that give identical answers. For how builds lost their meaning in the first place, see how this differs from semver.org.

The specification

How does this differ from semver.org?

Semantic Versions is a spiritual successor to Semantic Versioning 2.0.0-rc.1, the draft that introduced optional pre-release and build versions. The next draft, 2.0.0-rc.2, turned builds into inert “build metadata,” which made them semantically useless. Semantic Versions reverts that change, so builds participate in precedence again, and adds the definitions tools were already relying on without a spec: sets, ranges, operators and comparators.

Anything valid under Semantic Versioning 2.0.0 is valid here and parses identically. The topic-by-topic comparison is on the proposal page, and the history traces how builds lost their meaning.

Why MUST minor and patch reset to 0?

Resetting keeps versions a single, well-defined total order and gives every line an unambiguous first member: 2.5.0 is the start of the 2.5 series, and 2.0.0 is the start of the 2.x series. Tools that reason about “the first release of a minor” or that desugar ranges (~, ^, ~>) rely on this. A carried-forward counter like 2.5.1 with no 2.5.0 breaks that assumption.

The rule constrains carrying a lower-position counter forward, not skipping numbers. You MAY skip values: 2.4.10 → 2.6.0 → 4.0.0 is fine, because each increment still starts its lower positions at 0. What the rule forbids is 2.4.10 → 2.5.1: the minor incremented, so patch MUST restart at 0.

This is also why Semantic Versions keeps MUST rather than relaxing it to SHOULD (as proposed in semver/semver#393). A normative relaxation would fragment the ordering guarantees that existing Semantic Versioning 2.0.0 tooling depends on, for a gain you can already have by skipping the numbers you don't want.

Why keep MAJOR.MINOR.PATCH instead of renaming to BREAKING.FEATURE.FIX?

Backward compatibility is the whole pitch. Anything valid under Semantic Versioning 2.0.0 stays valid here, and MAJOR.MINOR.PATCH is the vocabulary the ecosystem already speaks: parsers, registries, changelog tools and a decade of habit. Renaming the positions would fragment all of that for a purely cosmetic gain, so the names stay.

The confusion the renaming proposals react to is real, though, and worth stating plainly: an increment reflects the nature of the change to your public API (incompatible, additive, or a fix), not the amount of code that changed. A complete internal rewrite that leaves the public API untouched is still a patch; a one-character change that removes a parameter is a major bump. The number you increment is decided by what the change does to the contract, never by how much work it was.

To keep that meaning attached to the familiar labels, the spec states the intent next to each name: MAJOR is an incompatible change, MINOR an additive change, PATCH a fix. And a patch is exactly that, a fix, not a promise of backward compatibility (nothing can truly guarantee that).

What counts as the “public API”, and is Semantic Versions for apps and products?

“Public API” is meant broadly: it is whatever public interface or contract you declare. That might be a library's function signatures, a CLI's flags and output, a GUI's documented behaviour, a wire protocol or a file format. The spec does not care which kind of interface it is; it only requires that you declare one and increment based on changes to it. If your software's contract is its command-line surface, that surface is your public API for versioning purposes.

What a version is about is named by its context: source:name@version (for example npm:react@18.2.0) identifies a specific artifact in a specific ecosystem, the thing whose interface you are versioning, rather than leaving a bare 1.2.3 to mean whatever the reader assumes.

Because of that, Semantic Versions targets a declared interface, not a product's marketing, feature set or billing cadence. A “product version” that jumps to 2.0.0 for a licensing change, or that must land features on a planned 1.5.0, follows a different scheme, one where the number communicates roadmap or pricing rather than interface compatibility. That is a legitimate thing to want, but it is not what a semantic version measures. If you need both, version the declared interface semantically and give the product its own separate label.

What does the spec mean by “deprecated”?

Deprecation is a documentation and registry concern, not version syntax. The spec references it once (a minor MUST be incremented when public API functionality is marked as deprecated) and deliberately defines no notation for it. None is planned.

The reason is that deprecation is retroactive while a version string is not. You deprecate 1.2.3 after publishing it, often long after, and registries model this as mutable metadata attached to an already-published version. But the contents of a released version MUST NOT be modified, and its version string is fixed at publish time. There is no moment at which the string could be rewritten to record a decision made later.

Encoding it anyway would break precedence in both available slots. A pre-release lowers precedence and announces instability, which is not what a deprecation says: a deprecated release is usually stable, just unwanted. A build is worse. Because a build participates in precedence here, 1.2.3+deprecated would sort above 1.2.3 and be preferred by every range that matched it. The deprecated release would win, which is precisely backwards.

So mark deprecations in your documentation and in your registry's metadata, and ship the announcement in a minor release. A version number records what changed in the declared interface; it does not carry advice about whether to use a release. That advice is real and worth publishing; it simply belongs somewhere mutable.

Ecosystem

Do I still need Package-URL (purl)?

For most uses, no. A source-qualified context already identifies a package version across ecosystems: npm:react@18.2.0 names the same thing as pkg:npm/react@18.2.0. The difference is what comes with it. A purl is only an identifier: it says nothing about how versions order or match, and leaves ranges to a separate syntax (vers). A Semantic Versions reference carries its semantics with it: precedence (builds included), sets, ranges and comparators, defined once and shared by every ecosystem.

The rest of a purl has a place here too. Platform and distribution qualifiers (?arch=…&os=…) sit outside a purl’s version, so nothing can order or select by them; as Build Variants they live in the build, where ranges can select them. An origin other than the public registry is just another source (internal:billing@2.4.0).

Where a tool or SBOM format still asks for a purl, converting is mechanical: source:name@version becomes pkg:source/name@version, with an npm scope or Maven group moving into its namespace segment (npm:@vue/cli@5.0.8 becomes pkg:npm/%40vue/cli@5.0.8). Using the familiar ecosystem tokens as sources (npm, pypi, gem, cargo, golang, maven, nuget, composer, oci) keeps that conversion one-to-one.

How does it work with Python’s PEP 440?

PEP 440 is the other widely used version grammar, and it recommends Semantic Versioning for the public release segment. Because Semantic Versions restores the two things Semantic Versioning 2.0.0 discarded, build precedence and default pre-release exclusion, it lines up with PEP 440’s ordering model more closely than 2.0.0 does. What follows is the interoperable subset; it adds no grammar or precedence rules to the specification.

Compatible subset

A version round-trips between the two schemes when it stays within this subset:

  1. The release segment is exactly three components (MAJOR.MINOR.PATCH) with no leading zeroes. PEP 440 permits an arbitrary-length release segment, but recommends this form.
  2. Pre-releases use the spellings -a.N (alpha), -b.N (beta) and -rc.N (release candidate). These sort correctly under Semantic Versions precedence (a < b < rc, then numerically), and map onto PEP 440’s normalized aN / bN / rcN pre-release segments.

Ordering alignment

  • Local versions ↔ builds. PEP 440 local versions (1.0.0+abc) participate in ordering and rank a labelled artifact above its plain release. Semantic Versions’ restored build precedence does the same (1.0.0 < 1.0.0+build), where Semantic Versioning 2.0.0 discards it.
  • Default pre-release exclusion. A range of stable comparators admits no pre-releases unless it opts in (see pre-release channels), mirroring pip’s requirement of --pre.
  • Post-releases. PEP 440 post-releases (1.0.0.post1) rank above the release, matching the “refinement above the release” shape of build precedence, though the two are not byte-for-byte convertible (see below).

Specifier mapping

PEP 440 specifierSemantic Versions range
~=1.4.2~1.4.2 (>=1.4.2 <1.5.0-0)
~=1.4^1.4 (>=1.4.0 <2.0.0-0)
==1.4.*1.4.x (>=1.4.0 <1.5.0-0)
>=1.4.2, >1.4.2, <=1.4.2, <1.4.2same operator, identical meaning
==1.4.21.4.2

Not representable

These PEP 440 constructs have no Semantic Versions equivalent and are deliberately left unmapped rather than special-cased:

  • Epochs (1!1.0): an epoch cannot be encoded without breaking Semantic Versioning 2.0.0 compatibility.
  • Development releases (.devN): PEP 440 sorts a dev release below its own parent pre-release (1.0.0-a.1.dev.1 < 1.0.0-a.1), which contradicts the rule that a larger set of identifiers ranks higher.
  • Exact post-release numerics (.postN): the “above the release” concept maps onto build precedence, but the precise .postN counter semantics do not survive the round trip.

The project

Where is the grammar?

Backus–Naur forms for versions, ranges and comparators are published on the grammar page, alongside the reference parser, semantic-versions. For quick validation there is also a regular expression, and you can try ranges against the parser in your browser.

Ports of the parser for Rust, Python, Go, Ruby, Java, .NET and PHP pass the same conformance suite; they are listed, with benchmarks, on the libraries page.

Is there a talk about it?

Yes. Spec-tacular: SemVer & Beyond, from DevOps.js Conf 2024, is 21 minutes on where the Semantic Versioning spec falls short and what it takes to close the gaps. It is background, not part of the specification.

Darcy Clarke · DevOps.js Conf 2024 · 21 min

Can I contribute, or propose an extension?

Yes. The specification, reference parser and extensions are developed in the open at vltpkg/semantic-versions. Open an issue or discussion to propose a change, report a defect, or float a new extension. Anything that rides on a source-qualified version and restored build precedence is in scope.

How is it licensed?

The specification text is licensed under CC BY 3.0, the reference parser under Apache 2.0. See the license page for details and attribution.