[GH-ISSUE #1148] ✨ Proposal: Clarify SemVer handling of build metadata and equality #7667

New Issue

GiteaMirror · 2026-06-20T17:45:36-05:00

GiteaMirror commented

2026-06-20 17:45:36 -05:00

Originally created by @erify-world on GitHub (Sep 7, 2025).
Original GitHub issue: https://github.com/semver/semver/issues/1148

Context

While SemVer 2.0.0 specifies that build metadata (+...) does not affect precedence, there’s ambiguity in how equality should be interpreted across implementations.

For example:
• 1.0.0+build.1 vs. 1.0.0+exp.sha.5114f85
• Should these be considered equal (since build metadata is ignored for precedence), or distinct (since the metadata differs)?

⸻

Problem
• Different tooling ecosystems (npm, Maven, Cargo, etc.) treat equality and metadata differently.
• This creates interoperability issues when comparing, caching, or distributing artifacts.

⸻

Proposal
1. Clarify Equality Rule:
Explicitly state whether two versions differing only by build metadata should be considered equal.
2. Reference Examples:
Add normative examples to the specification, e.g.:
• 1.0.0+abc == 1.0.0+xyz (if build metadata is ignored)
• Or explicitly declare them distinct (if metadata counts).
3. Impact Assessment:
• How will this affect existing package managers?
• Should metadata equality be left implementation-defined, or standardized?

⸻

Motivation
• Ensures cross-tool consistency.
• Reduces ambiguous comparisons across ecosystems.
• Provides clear guidance for future spec versions (e.g., SemVer 3.0).

⸻

🔗 Related Issues:
• Equality and build metadata
• Proposed v2.0.1

Originally created by @erify-world on GitHub (Sep 7, 2025). Original GitHub issue: https://github.com/semver/semver/issues/1148 Context While SemVer 2.0.0 specifies that build metadata (+...) does not affect precedence, there’s ambiguity in how equality should be interpreted across implementations. For example: • 1.0.0+build.1 vs. 1.0.0+exp.sha.5114f85 • Should these be considered equal (since build metadata is ignored for precedence), or distinct (since the metadata differs)? ⸻ Problem • Different tooling ecosystems (npm, Maven, Cargo, etc.) treat equality and metadata differently. • This creates interoperability issues when comparing, caching, or distributing artifacts. ⸻ Proposal 1. Clarify Equality Rule: Explicitly state whether two versions differing only by build metadata should be considered equal. 2. Reference Examples: Add normative examples to the specification, e.g.: • 1.0.0+abc == 1.0.0+xyz (if build metadata is ignored) • Or explicitly declare them distinct (if metadata counts). 3. Impact Assessment: • How will this affect existing package managers? • Should metadata equality be left implementation-defined, or standardized? ⸻ Motivation • Ensures cross-tool consistency. • Reduces ambiguous comparisons across ecosystems. • Provides clear guidance for future spec versions (e.g., SemVer 3.0). ⸻ 🔗 Related Issues: • [Equality and build metadata](https://github.com/semver/semver/issues/1134) • [Proposed v2.0.1](https://github.com/semver/semver/issues/1120)

GiteaMirror commented

2026-06-20 17:45:38 -05:00

@ljharb commented on GitHub (Sep 7, 2025):

I'm not sure why there's ambiguity - 1.0.0+build.1 is objectively not equal to 1.0.0+exp.sha.5114f85.

However, in a system like npm that ignores build metadata, 1.0.0+build.1 is reduced to 1.0.0, as is 1.0.0+exp.sha.5114f85 - so they resolve to the same version.

@ljharb commented on GitHub (Sep 7, 2025): I'm not sure why there's ambiguity - `1.0.0+build.1` is objectively not equal to `1.0.0+exp.sha.5114f85`. However, in a system like npm that ignores build metadata, `1.0.0+build.1` is reduced to `1.0.0`, as is `1.0.0+exp.sha.5114f85` - so they resolve to the same version.

GiteaMirror commented

2026-06-20 17:45:38 -05:00

@norman-abramovitz commented on GitHub (Oct 20, 2025):

The spec makes it clear that information after the + does not play a role in comparing semver strings. if you want the information to compared it needs to be in the - section. Think the + section as comments.

@norman-abramovitz commented on GitHub (Oct 20, 2025): The spec makes it clear that information after the + does not play a role in comparing semver strings. if you want the information to compared it needs to be in the - section. Think the + section as comments.

GiteaMirror commented

2026-06-20 17:45:39 -05:00

@ljharb commented on GitHub (Oct 22, 2025):

The spec says

Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence.

Comparing two versions for equality is not for determining version precedence.

@ljharb commented on GitHub (Oct 22, 2025): [The spec](https://semver.org/#spec-item-10) says > Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Comparing two versions for equality is not for determining version precedence.

GiteaMirror commented

2026-06-20 17:45:39 -05:00

@norman-abramovitz commented on GitHub (Oct 23, 2025):

I cannot tell if we are agreeing or not. The spec allows for version comparison only. The prerelease section is lower precedence.

The spec intentionally does not define whole string comparison. Just like adding a v in front of the major number is not a semver string.

Whole string comparison is out of scope for this version of the spec.

@norman-abramovitz commented on GitHub (Oct 23, 2025): I cannot tell if we are agreeing or not. The spec allows for version comparison only. The prerelease section is lower precedence. The spec intentionally does not define whole string comparison. Just like adding a v in front of the major number is not a semver string. Whole string comparison is out of scope for this version of the spec.

GiteaMirror commented

2026-06-20 17:45:40 -05:00

@ljharb commented on GitHub (Oct 23, 2025):

Right - this issue is asking about whole string comparison of the semver string - in which case, regardless of the spec's silence on the matter, I'd say the only possible interpretation is that 1.0.0+build.1 is not equal to 1.0.0+exp.sha.5114f85

@ljharb commented on GitHub (Oct 23, 2025): Right - this issue is asking about whole string comparison of the semver string - in which case, regardless of the spec's silence on the matter, I'd say the only possible interpretation is that `1.0.0+build.1` is not equal to `1.0.0+exp.sha.5114f85`

GiteaMirror commented

2026-06-20 17:45:41 -05:00

@norman-abramovitz commented on GitHub (Oct 29, 2025):

I am playing devil's advocate here (i.e., proposing a different interpretation on purpose to see where it leads).

Given your example strings
1.0.0+build.1
1.0.0+exp.sha.5114f85

Your two strings are providing different information. One gives build information, and the other gives exp. sha information.
Performing a whole string comparison would be invalid even if you want to compare the complete strings.
As some people say, it is like comparing apples to oranges., They are both fruits, but they are totally different things.

Nothing in the specification stops you from having multiple version strings for a project.
So, staying within the specification, these two strings are equal, but convey different information. I believe that is what npm is doing.

@norman-abramovitz commented on GitHub (Oct 29, 2025): I am playing devil's advocate here (i.e., proposing a different interpretation on purpose to see where it leads). Given your example strings 1.0.0+build.1 1.0.0+exp.sha.5114f85 Your two strings are providing different information. One gives build information, and the other gives exp. sha information. Performing a whole string comparison would be **invalid** even if you want to compare the complete strings. As some people say, it is like comparing apples to oranges., They are both fruits, but they are totally different things. Nothing in the specification stops you from having multiple version strings for a project. So, staying within the specification, these two strings are equal, but convey different information. I believe that is what npm is doing.

GiteaMirror commented

2026-06-20 17:45:41 -05:00

@smilly-boy commented on GitHub (Dec 29, 2025):

Context

While SemVer 2.0.0 specifies that build metadata (+...) does not affect precedence, there’s ambiguity in how equality should be interpreted across implementations.

For example: • 1.0.0+build.1 vs. 1.0.0+exp.sha.5114f85 • Should these be considered equal (since build metadata is ignored for precedence), or distinct (since the metadata differs)?

⸻

Problem • Different tooling ecosystems (npm, Maven, Cargo, etc.) treat equality and metadata differently. • This creates interoperability issues when comparing, caching, or distributing artifacts.

⸻

Proposal 1. Clarify Equality Rule: Explicitly state whether two versions differing only by build metadata should be considered equal. 2. Reference Examples: Add normative examples to the specification, e.g.: • 1.0.0+abc == 1.0.0+xyz (if build metadata is ignored) • Or explicitly declare them distinct (if metadata counts). 3. Impact Assessment: • How will this affect existing package managers? • Should metadata equality be left implementation-defined, or standardized?

⸻

Motivation • Ensures cross-tool consistency. • Reduces ambiguous comparisons across ecosystems. • Provides clear guidance for future spec versions (e.g., SemVer 3.0).

⸻

🔗 Related Issues: • Equality and build metadata • Proposed v2.0.1

@smilly-boy commented on GitHub (Dec 29, 2025): > Context > > While SemVer 2.0.0 specifies that build metadata (+...) does not affect precedence, there’s ambiguity in how equality should be interpreted across implementations. > > For example: • 1.0.0+build.1 vs. 1.0.0+exp.sha.5114f85 • Should these be considered equal (since build metadata is ignored for precedence), or distinct (since the metadata differs)? > > ⸻ > > Problem • Different tooling ecosystems (npm, Maven, Cargo, etc.) treat equality and metadata differently. • This creates interoperability issues when comparing, caching, or distributing artifacts. > > ⸻ > > Proposal 1. Clarify Equality Rule: Explicitly state whether two versions differing only by build metadata should be considered equal. 2. Reference Examples: Add normative examples to the specification, e.g.: • 1.0.0+abc == 1.0.0+xyz (if build metadata is ignored) • Or explicitly declare them distinct (if metadata counts). 3. Impact Assessment: • How will this affect existing package managers? • Should metadata equality be left implementation-defined, or standardized? > > ⸻ > > Motivation • Ensures cross-tool consistency. • Reduces ambiguous comparisons across ecosystems. • Provides clear guidance for future spec versions (e.g., SemVer 3.0). > > ⸻ > > 🔗 Related Issues: • [Equality and build metadata](https://github.com/semver/semver/issues/1134) • [Proposed v2.0.1](https://github.com/semver/semver/issues/1120)

GiteaMirror commented

2026-06-20 17:45:42 -05:00

@Aranmobinarann commented on GitHub (Jan 27, 2026):

Hello
Ok🙂
Formally define 'semantic equality' where build metadata is entirely ignored. Two versions are considered equal if their major.minor.patch-pre-release identifiers are identical..
Justification:
Aligns with SemVer philosophy
Follows common existing behavior..
Prevents duplicate versions with different build metadata.
Improves tooling interoperability..👍🙂

@Aranmobinarann commented on GitHub (Jan 27, 2026): Hello Ok🙂 Formally define 'semantic equality' where build metadata is entirely ignored. Two versions are considered equal if their major.minor.patch-pre-release identifiers are identical.. Justification: Aligns with SemVer philosophy Follows common existing behavior.. Prevents duplicate versions with different build metadata. Improves tooling interoperability..👍🙂

GiteaMirror commented

2026-06-20 17:45:43 -05:00

@jwdonahue commented on GitHub (Mar 10, 2026):

@Aranmobinarann

Prevents duplicate versions with different build metadata.

That depends on the infrastructure you are using. Some packaging tools are perfectly happy to apply multiple version strings, with differing metadata, to the same content. Some aren't quite that picky, and will allow multiple entries that vary only in metadata (useful in massively parallel build systems), whether their content is the same or not, but they require you to be explicit regarding which package you want to pull, if there is more than one.

For compliance purposes, there should never be 2 package content hashes in the wild, with the same version string (ignoring meta). Most tool chains don't actually work hard enough to prevent this.

Some, like NPM, simply toss the metadata. Or at least they used to, and that makes it a little harder for multiple devs working in the same code space, to silently bifurcate their customer base.

@jwdonahue commented on GitHub (Mar 10, 2026): @Aranmobinarann > Prevents duplicate versions with different build metadata. That depends on the infrastructure you are using. Some packaging tools are perfectly happy to apply multiple version strings, with differing metadata, to the same content. Some aren't quite that picky, and will allow multiple entries that vary only in metadata (useful in massively parallel build systems), whether their content is the same or not, but they require you to be explicit regarding which package you want to pull, if there is more than one. For compliance purposes, there should never be 2 package content hashes in the wild, with the same version string (ignoring meta). Most tool chains don't actually work hard enough to prevent this. Some, like NPM, simply toss the metadata. Or at least they used to, and that makes it a little harder for multiple devs working in the same code space, to silently bifurcate their customer base.

GiteaMirror commented

2026-06-20 17:45:43 -05:00

@m9228304320-rgb commented on GitHub (Jun 20, 2026):

Concreten su propuesta xque están ya exigiendo cambios visibles en el sistema

Le daremos un giro a esto así que aloquense con con sus propuestas porque probablemente todas se tomen en cuenta para un desarrollo colectivo conforme y parejo.

No se preocupen por quien soy o de donde vengo, lo importante es que llegó a ustedes está información.

Estén atentos.

@m9228304320-rgb commented on GitHub (Jun 20, 2026): Concreten su propuesta xque están ya exigiendo cambios visibles en el sistema Le daremos un giro a esto así que aloquense con con sus propuestas porque probablemente todas se tomen en cuenta para un desarrollo colectivo conforme y parejo. No se preocupen por quien soy o de donde vengo, lo importante es que llegó a ustedes está información. Estén atentos.

GiteaMirror commented

2026-06-20 17:45:44 -05:00

@m9228304320-rgb commented on GitHub (Jun 20, 2026):

Y hagan propuestas más relevantes como hacer posible que se pueda programar individualmente o algo asii

@m9228304320-rgb commented on GitHub (Jun 20, 2026): Y hagan propuestas más relevantes como hacer posible que se pueda programar individualmente o algo asii

GiteaMirror commented

2026-06-20 17:45:44 -05:00

@m9228304320-rgb commented on GitHub (Jun 20, 2026):

O que cada quien genere su propia línea de código personal o que se yo

@m9228304320-rgb commented on GitHub (Jun 20, 2026): O que cada quien genere su propia línea de código personal o que se yo

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#7667