Definition
How do you communicate to your users whether an update is safe to install or might break everything? Semantic Versioning (SemVer) answers this with a simple three-number system: MAJOR.MINOR.PATCH. Each number tells you something specific about what changed, so users can make informed decisions about upgrading.
The rules are straightforward: increment MAJOR when you make incompatible changes (things that will break existing code), increment MINOR when you add features in a backward-compatible way (new stuff, nothing breaks), and increment PATCH when you fix bugs without changing functionality (just fixes, everything works as before). Version 2.4.1 tells you instantly: this is the second major iteration, with 4 feature updates since then, and 1 bug fix since the last feature.
This matters enormously in the real world because software depends on other software. Your app might use a library, which uses another library, which uses three more. When one of those deep dependencies releases an update, you need to know: is this safe? Will it break my app? A patch update (2.4.1 to 2.4.2) should be completely safe. A minor update (2.4.1 to 2.5.0) adds features but should not break existing code. A major update (2.4.1 to 3.0.0) might require changes to your code. This communication protocol lets thousands of packages coexist and update without chaos.
Example
npm packages: When you run npm install express, npm uses SemVer to manage dependencies. Your package.json might say "express": "^4.18.2", meaning “install version 4.18.2 or any compatible update in the 4.x range.”
iPhone iOS updates: Apple uses a SemVer-like system. iOS 16 to iOS 17 was a major update with significant changes. iOS 17.0 to iOS 17.1 was a minor update with new features. iOS 17.1.1 was a patch fixing bugs.
Chrome browser versions: Chrome 118.0.5993.88 follows SemVer principles. Major version 118 indicates the feature release cycle, and the patch numbers show smaller fixes.
API versioning: When Stripe’s API goes from v2023-08-16 to v2024-01-15, the date-based format serves a similar purpose - letting you know when significant changes occurred.
Analogy
The Car Model System: Think about how cars are versioned. A completely redesigned model (new generation) is like a major version - everything changed. A mid-cycle refresh with new features (updated infotainment, new engine option) is a minor version. A recall fix for a specific problem is a patch. The 2024 Honda Civic 2.0L Sport is telling you generation (2024 redesign), variant (2.0L), and trim (Sport).
The Textbook Edition System: Textbooks use a similar concept. A new edition (5th to 6th edition) might reorganize chapters and update content significantly - that is a major change. A revised printing fixes typos and errors - that is a patch. The edition number tells students whether they can use an older version for class.
The Recipe Version: Imagine a chef’s recipe. Changing the main protein (chicken to fish) is a major change - it is a different dish. Adding a garnish or side is a minor change - new features, same dish. Fixing a typo in the cooking time is a patch - just a correction.
The Software Update Dialog: You know how your phone sometimes says “important security update” versus “new features available”? That is essentially communicating patch versus minor updates in user-friendly language.
Code Example
// Semantic versioning in APIs
GET /v2.4.1/payments // Full version
GET /v2/payments // Major version only (recommended)
// Version in response headers
[HTTP/1.1](https://reference.apios.info/terms/http-1-1/) 200 OK
X-API-Version: 2.4.1
// SemVer interpretation:
// 1.0.0 → Initial release
// 1.1.0 → Added new payment method (backwards-compatible)
// 1.1.1 → Fixed tax calculation bug
// 2.0.0 → Changed authentication model (BREAKING)
// 2.1.0 → Added subscription endpoints
// 2.1.1 → Fixed webhook retry logic
// Version compatibility
{
"apiVersion": "2.4.1",
"minimumClientVersion": "2.0.0",
"deprecatedVersions": ["1.x"],
"sunset": {
"version": "1.x",
"date": "2025-12-31"
}
}