# Semantic Version Comparator

> Parses two Semantic Versioning 2.0.0 strings, orders them by the specification's precedence rules (numeric core, then pre-release identifiers; build metadata ignored) and reports whether the second version satisfies the npm-style ^ (caret) and ~ (tilde) ranges of the first.

- Calculator id: `semver-compare` · Category: Developer & IT (`developer`) · Tool name: `compare_semver_versions`
- Canonical page: https://tttkmbb.com/developer/semver-compare · This document: https://tttkmbb.com/developer/semver-compare.md · JSON definition: https://tttkmbb.com/developer/semver-compare.json

## Purpose

Parses two Semantic Versioning 2.0.0 strings, orders them by the specification's precedence rules (numeric core, then pre-release identifiers; build metadata ignored) and reports whether the second version satisfies the npm-style ^ (caret) and ~ (tilde) ranges of the first.

**Use when:** You need to know which of two versions is newer, whether 1.0.0-rc.1 precedes 1.0.0, or whether a dependency range such as ^1.2.3 would accept a candidate version.

**Do not use when:** The versions are not SemVer (calendar versions, four-part Windows versions, Python PEP 440 with .post/.dev) or you need to resolve full range expressions with || and comparators.

## Input

| Parameter | Type | Unit | Required | Description |
| --- | --- | --- | --- | --- |
| `version_a` | string |  | required | First version, e.g. 1.0.0-alpha or v2.3.4+build.5 (leading v allowed). |
| `version_b` | string |  | required | Second version to compare against A. |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `comparison` | string |  | A < B, A = B or A > B written with the actual version strings. |
| `result` | integer |  | −1 when A precedes B, 0 when they have equal precedence, 1 when A is higher. |
| `difference` | string |  | Which part decides the order: major, minor, patch, prerelease, or equal (build metadata only, or identical). |
| `parsed_a` | object |  | major, minor, patch, prerelease and build of version A. |
| `parsed_b` | object |  | major, minor, patch, prerelease and build of version B. |
| `is_prerelease_a` | boolean |  | true when A carries a pre-release tag. |
| `is_prerelease_b` | boolean |  | true when B carries a pre-release tag. |
| `satisfies_caret` | boolean |  | Whether ^A (compatible with A: same major, or same minor when major is 0) accepts B. |
| `satisfies_tilde` | boolean |  | Whether ~A (patch-level changes only: ≥ A and < next minor) accepts B. |
| `caret_range` | string |  | The caret range of A written as >=A <upper. |
| `tilde_range` | string |  | The tilde range of A written as >=A <upper. |

## Formula

`Precedence: compare major, minor, patch numerically; a version with a pre-release tag is lower than the same version without; pre-release identifiers are compared left to right (numeric < alphanumeric, numeric by value, alphanumeric by ASCII, shorter list lower); build metadata is ignored`

SemVer 2.0.0 items 9–11. Caret and tilde follow node-semver: ^1.2.3 = >=1.2.3 <2.0.0, ^0.2.3 = >=0.2.3 <0.3.0, ^0.0.3 = >=0.0.3 <0.0.4, ~1.2.3 = >=1.2.3 <1.3.0; a pre-release B only satisfies a range when A is a pre-release of the same major.minor.patch.

## Data Sources

- Semantic Versioning 2.0.0 (semver.org) — https://semver.org/spec/v2.0.0.html (standard, retrieved 2026-09-24)
- node-semver – Ranges, caret and tilde semantics (npm) — https://github.com/npm/node-semver#ranges (reference, retrieved 2026-09-24)

Data freshness: `static`. Deterministic formula with fixed constants; results never go stale. Inputs supplied by the caller determine the output.

## API

- `GET https://tttkmbb.com/api/v1/calculate/semver-compare?version_a=…&version_b=…`
- `POST https://tttkmbb.com/api/v1/calculate/semver-compare` with JSON body `{"inputs": {…}}`
- Response: unified envelope (`success`, `request`, `result.values`, `result.units`, `sources`, `freshness`, `timestamp`, `next_actions`, `links`); see https://tttkmbb.com/docs/response-format.md
- Schema: https://tttkmbb.com/api/v1/calculators/semver-compare · OpenAPI operationId `compare_semver_versions` in https://tttkmbb.com/openapi.json
- Authentication: none. Rate limit: fair use, see https://tttkmbb.com/docs/rate-limits.md.

## MCP

- Server: `https://tttkmbb.com/mcp` (Streamable HTTP, JSON-RPC 2.0, no auth)
- Tool:  `run_calculator` with `{"calculator_id": "semver-compare", "inputs": {…}}`

## Example

- 1.0.0-alpha vs 1.0.0: inputs `{"version_a":"1.0.0-alpha","version_b":"1.0.0"}` → `{"result":-1,"comparison":"1.0.0-alpha < 1.0.0","difference":"prerelease","is_prerelease_a":true,"is_prerelease_b":false,"satisfies_caret":true,"satisfies_tilde":true,"parsed_a":{"major":1,"minor":0,"patch":0,"prerelease":"alpha","build":""}}`
- 1.10.0 vs 1.9.9: inputs `{"version_a":"1.10.0","version_b":"1.9.9"}` → `{"result":1,"comparison":"1.10.0 > 1.9.9","difference":"minor","satisfies_caret":false,"satisfies_tilde":false,"caret_range":">=1.10.0 <2.0.0","tilde_range":">=1.10.0 <1.11.0"}`

```
GET https://tttkmbb.com/api/v1/calculate/semver-compare?version_a=1.0.0-alpha&version_b=1.0.0
```

## Limitations

The versions are not SemVer (calendar versions, four-part Windows versions, Python PEP 440 with .post/.dev) or you need to resolve full range expressions with || and comparators. SemVer 2.0.0 items 9–11. Caret and tilde follow node-semver: ^1.2.3 = >=1.2.3 <2.0.0, ^0.2.3 = >=0.2.3 <0.3.0, ^0.0.3 = >=0.0.3 <0.0.4, ~1.2.3 = >=1.2.3 <1.3.0; a pre-release B only satisfies a range when A is a pre-release of the same major.minor.patch. All values are computed from the formula above; no measurement or live data is involved.

## FAQ

**Why is 1.0.0-beta.11 higher than 1.0.0-beta.2?**

Numeric pre-release identifiers are compared as numbers (11 > 2), not as strings; 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

**Do 1.0.0+build.1 and 1.0.0+build.2 differ?**

Not in precedence: build metadata is ignored when ordering, so they compare as equal (result 0, difference 'equal').

**Why does ^0.2.3 not accept 0.3.0?**

Below 1.0.0 the minor version is treated as the breaking level, so ^0.2.3 means >=0.2.3 <0.3.0 in npm and Cargo.

## Related

- [Cron Schedule Calculator](https://tttkmbb.com/developer/cron-schedule.md) — Another developer-tooling parser.
- [Text Hash Calculator](https://tttkmbb.com/developer/text-hash.md) — Fingerprint a release artifact.