Coerce a Loose Version String into Valid SemVer

Coercing Loose Version Strings

Real-world version strings are messy. Applications, APIs, and legacy systems often use formats that are not valid SemVer. Coercion is the process of extracting a valid semver from these loose strings.

Common Loose Formats

Loose String	Coerced SemVer	Rule Applied
v2.1.0	2.1.0	Strip "v" prefix
2.1	2.1.0	Append missing PATCH as 0
3	3.0.0	Append missing MINOR and PATCH
1.2.3.4	1.2.3	Drop extra components
1.2.3	1.2.3	Trim whitespace
=1.2.3	1.2.3	Strip leading operator
v2.1.0-beta	2.1.0-beta	Strip prefix, keep pre-release

When Coercion Is Safe

Coercion works well when:

• Displaying versions: Converting Git tags (v1.2.3) for user display
• Sorting mixed formats: Normalizing a list of versions from different sources
• Loose input fields: Accepting user input that is "close enough" to SemVer

When Coercion Is Dangerous

Coercion should be avoided when:

• Publishing packages: Always require strict SemVer for package registries
• Comparing for equality: 1.2 coerced to 1.2.0 may not mean what the author intended
• Four-part versions: 1.2.3.4 might be a .NET assembly version where the 4th part matters

Coercion Algorithm

A typical coercion algorithm:

1. Trim whitespace
2. Strip leading v, V, or =
3. Extract the first three dot-separated numeric groups
4. Fill missing groups with 0
5. Preserve pre-release and build metadata if present

The npm Approach

npm's semver.coerce() function scans the string for the first occurrence of a number and tries to build a version from it. For example, semver.coerce("version 4.2 is great") returns 4.2.0. This is intentionally aggressive to handle version strings embedded in prose or filenames.