[GH-ISSUE #537] Sub-labels for dot-separated pre-release and build identifiers #7369

New Issue

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

GiteaMirror commented

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

Originally created by @zfields on GitHub (Oct 15, 2019).
Original GitHub issue: https://github.com/semver/semver/issues/537

I need a way to describe SemVer in an object.

For example: 1.0.0-alpha.1

You have supplied names for major, minor and patch, but the remaining sub-components are too loosely defined to have names.

To normalize/standardize the dot-separated pre-release and build identifiers, can the specification be updated to refer to the sub-components as label and id?

{
    "major": 1,
    "minor": 0,
    "patch": 0,
    "pre-release": [
        {
            "label": "alpha",
            "id": 1
        }
    ],
    "build": [ ]
}

Originally created by @zfields on GitHub (Oct 15, 2019). Original GitHub issue: https://github.com/semver/semver/issues/537 I need a way to describe SemVer in an object. For example: `1.0.0-alpha.1` You have supplied names for `major`, `minor` and `patch`, but the remaining sub-components are too loosely defined to have names. To normalize/standardize the dot-separated pre-release and build identifiers, can the specification be updated to refer to the sub-components as `label` and `id`? ```json { "major": 1, "minor": 0, "patch": 0, "pre-release": [ { "label": "alpha", "id": 1 } ], "build": [ ] } ```

GiteaMirror added the question label 2026-06-20 17:23:36 -05:00

GiteaMirror commented

2026-06-20 17:23:37 -05:00

@ljharb commented on GitHub (Oct 15, 2019):

I think it's just "major", "minor", "patch", and "prerelease" - ie, there's nothing more granular there than alpha.1.

@ljharb commented on GitHub (Oct 15, 2019): I think it's just "major", "minor", "patch", and "prerelease" - ie, there's nothing more granular there than `alpha.1`.

GiteaMirror commented

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

@zfields commented on GitHub (Oct 15, 2019):

I see now that the pre-release rule is - (hypen) followed by an infinite number of alpha-numeric combinations seperated by . (periods), and the build metadata rule is + (plus) followed by an infinite number of alpha-numeric combinations seperated by . (periods).

While certainly more flexible, it is much harder to reason about an array.

Is it in anyone's interest to have more order/structure provided to pre-release and build metadata?

@zfields commented on GitHub (Oct 15, 2019): I see now that the **pre-release rule** is `-` _(hypen)_ followed by an infinite number of alpha-numeric combinations seperated by `.` _(periods)_, and the **build metadata rule** is `+` _(plus)_ followed by an infinite number of alpha-numeric combinations seperated by `.` _(periods)_. While certainly more flexible, it is much harder to reason about an array. Is it in anyone's interest to have more order/structure provided to **pre-release** and **build metadata**?

GiteaMirror commented

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

@zfields commented on GitHub (Oct 15, 2019):

I would love to have the discussion, then this is fine to close.

@zfields commented on GitHub (Oct 15, 2019): I would love to have the discussion, then this is fine to close.

GiteaMirror commented

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

@jeme commented on GitHub (Oct 15, 2019):

I think it's safe to say that this is outside the scope of the SemVer spec which deals with the string format only, for whatever reason you need to describe your SemVer as an object, it's certainly application and/or language specific which the SemVer spec is not.

@jeme commented on GitHub (Oct 15, 2019): I think it's safe to say that this is outside the scope of the SemVer spec which deals with the string format only, for whatever reason you need to describe your SemVer as an object, it's certainly application and/or language specific which the SemVer spec is not.

GiteaMirror commented

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

@zfields commented on GitHub (Oct 15, 2019):

I disagree, the specification clearly states rules associated with major, minor and patch versions, not just string formatting.

It was not long ago that versions were as meaningless and abstract as pre-release and build metadata information is now.

It would make sense if the specification were extended into organizing pre-release and build metadata tags as well.

@zfields commented on GitHub (Oct 15, 2019): I disagree, the specification clearly states rules associated with major, minor and patch versions, not just string formatting. It was not long ago that versions were as meaningless and abstract as pre-release and build metadata information is now. It would make sense if the specification were extended into organizing pre-release and build metadata tags as well.

GiteaMirror commented

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

@jeme commented on GitHub (Oct 15, 2019):

The spec first and foremost defines a format of "MAJOR.MINOR.PATCH" or "X.Y.Z" (read §2) + pre and meta data, which does not fit into your object notation. It goes furter to provide a BNF grammar. I would say that it's pretty specifically targeting a text based format with those things in it.

Ones it has established a format, it then adds semantics to that format which makes us able to communicate more than just a "number" with it.

Why is it that you need the spec to state how you can store the information in an object for processing (or whatever it is your are using your object for)??? Why not just use the freedom at hand to specify that as you like?... I fail to see the purpose.

There are plenty of people out there that has implemented SemVer parsers around the spec that provides some form of interface to a SemVer version.

Just a few:

how compliant they each are I can't say, but none of them needed any changes to the spec to exist.

@jeme commented on GitHub (Oct 15, 2019): The spec first and foremost defines a format of "MAJOR.MINOR.PATCH" or "X.Y.Z" (read §2) + pre and meta data, which does not fit into your object notation. It goes furter to provide a BNF grammar. I would say that it's pretty specifically targeting a text based format with those things in it. Ones it has established a format, it then adds semantics to that format which makes us able to communicate more than just a "number" with it. Why is it that you need the spec to state how you can store the information in an object for processing (or whatever it is your are using your object for)??? Why not just use the freedom at hand to specify that as you like?... I fail to see the purpose. There are plenty of people out there that has implemented SemVer parsers around the spec that provides some form of interface to a SemVer version. Just a few: - https://github.com/asamuzaK/semverParser - https://docs.rs/semver-parser/0.9.0/semver_parser/ - https://github.com/maxhauser/semver - https://github.com/Ruhrpottpatriot/SemanticVersion - https://github.com/softprops/semverfi how compliant they each are I can't say, but none of them needed any changes to the spec to exist.

GiteaMirror commented

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

@zfields commented on GitHub (Oct 16, 2019):

That's a great perspective! Which is what I'm hoping to hear, by having a discussion.

Furthermore, I was not proposing the JSON above to be part of the specification, I was merely offering an example of something that is easy to programatically reason about.

It looks like today, 1.4.3-rc.3 can be parsed into the following JSON:

{
    "major": 1,
    "minor": 4,
    "patch": 3,
    "pre-release": [
        "rc",
        "3"
    ],
    "build": [ ]
}

My goal was to invoke a discussion about the value (if any) of bringing order to the chaos of pre-release and build metadata tokens.

@zfields commented on GitHub (Oct 16, 2019): That's a great perspective! Which is what I'm hoping to hear, by having a discussion. Furthermore, I was not proposing the JSON above to be part of the specification, I was merely offering an example of something that is easy to programatically reason about. It looks like today, `1.4.3-rc.3` can be parsed into the following JSON: ```json { "major": 1, "minor": 4, "patch": 3, "pre-release": [ "rc", "3" ], "build": [ ] } ``` My goal was to invoke a discussion about the value _(if any)_ of bringing order to the chaos of pre-release and build metadata tokens.

GiteaMirror commented

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

@zfields commented on GitHub (Oct 17, 2019):

I would love to hear the perspective of a member of the semver group, then please feel free to close this issue.

@zfields commented on GitHub (Oct 17, 2019): I would love to hear the perspective of a member of the semver group, then please feel free to close this issue.

GiteaMirror commented

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

@jwdonahue commented on GitHub (Oct 17, 2019):

@zfields

I believe your original post suggests imposing additional semantics on the prerelease tag, is that correct? If so, that would be a breaking change to the specification. In addition, it would highly restrict how the prerelease tag could be used. How do you propose to solve the disambiguation issues between SemVer 2.y.z version strings and SemVer 2+n.y.z?

It was not long ago that versions were as meaningless and abstract as pre-release and build metadata information is now.

That's not necessarily true. SemVer distilled and codified existing best practice of the day. Yes there were a lot of marketing driven and other version schemes out there, but if you ask any of the people who applied them, they would likely disagree with your assumption that their practices were chaotic. I would also add that there are many more versioning schemes in use today than there were back then, some of them well documented and supported.

You have to keep in mind that SemVer is currently maintained by a cabal of package tool owners, who are more likely to respond to their own customer's requests, than to someone who simply wishes to impose their idea of order on everyone else. A large web of tooling is evolving around this standard and any breaking changes to it, must be well thought out.

Unless you intend to issue a PR or have further questions, please close this issue at your earliest possible convenience.

@jwdonahue commented on GitHub (Oct 17, 2019): @zfields I believe your original post suggests imposing additional semantics on the prerelease tag, is that correct? If so, that would be a breaking change to the specification. In addition, it would highly restrict how the prerelease tag could be used. How do you propose to solve the disambiguation issues between SemVer 2.y.z version strings and SemVer 2+n.y.z? > It was not long ago that versions were as meaningless and abstract as pre-release and build metadata information is now. That's not necessarily true. SemVer distilled and codified existing best practice of the day. Yes there were a lot of marketing driven and other version schemes out there, but if you ask any of the people who applied them, they would likely disagree with your assumption that their practices were chaotic. I would also add that there are many more versioning schemes in use today than there were back then, some of them well documented and supported. You have to keep in mind that SemVer is currently maintained by a cabal of package tool owners, who are more likely to respond to their own customer's requests, than to someone who simply wishes to impose their idea of order on everyone else. A large web of tooling is evolving around this standard and any breaking changes to it, must be well thought out. Unless you intend to issue a PR or have further questions, please close this issue at your earliest possible convenience.

GiteaMirror commented

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

@zfields commented on GitHub (Oct 18, 2019):

@jwdonahue The tone of your response is not in the spirit of exploration and understanding, which is the spirit of this issue.

I am not attempting to impose any rules on anyone, only have the discussion about how semantics may affect the notion of pre-release and build metadata tags. In fact, I have asked repeatedly for discussion. Furthermore, I do appreciate you and the contribution of your viewpoint, viewpoints like yours are in fact what I am soliciting.

While I agree that each company, group or project had internal meaning for the version they were applying to their code base, I think it's fair to say there was no broad consensus on what a version should imply, until SemVer came into being.

To all others who wish to offer their opinion, I do look forward to reading it, but please offer it in the spirit of understanding and exploration.

Again, if an member of this project would like to offer their viewpoint on why pre-release and build metadata have been handled the way they have been, then I am very happy to consider that the conclusion of my inquiry, and they may feel free to close this issue at that time.

Cheers!

@zfields commented on GitHub (Oct 18, 2019): @jwdonahue The tone of your response is not in the spirit of exploration and understanding, which is the spirit of this issue. I am not attempting to impose any rules on anyone, only have the discussion about how semantics may affect the notion of pre-release and build metadata tags. In fact, I have asked repeatedly for discussion. Furthermore, I do appreciate you and the contribution of your viewpoint, viewpoints like yours are in fact what I am soliciting. While I agree that each company, group or project had internal meaning for the version they were applying to their code base, I think it's fair to say there was no broad consensus on what a version should imply, until SemVer came into being. To all others who wish to offer their opinion, I do look forward to reading it, but please offer it in the spirit of understanding and exploration. Again, if an member of this project would like to offer their viewpoint on why pre-release and build metadata have been handled the way they have been, then I am very happy to consider that the conclusion of my inquiry, and they may feel free to close this issue at that time. Cheers!

GiteaMirror commented

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

@jwdonahue commented on GitHub (Oct 20, 2019):

I think it's fair to say there was no broad consensus on what a version should imply, until SemVer came into being

That's a very software oriented view, and a myopic one, even within that narrow field. Version labeling of various published artifacts has been going on for thousands of years. If you bother to search, you should find a very long list of papers published/presented to various IEEE and ACM interest groups dating back decades. The DOD and DOE also have written standards/guidelines that predate SemVer by decades. I am sure that AT&T and IBM have contributed a host of "standards" as well, and I know various teams within Microsoft have their own.

Prior to SemVer, lacking any refining information, a software version label, was just that. A label indicating what version of the software it was attached to. That is still the case today. Even version strings that are known to purport compliance with the SemVer standard, meet that minimum bar, in most but no all cases. At least that is usually the intent. We can't ignore the fact that version strings provide weak guarantees regarding the uniqueness of the versioned product. It is all too common to find packages with identical labels and differing content signatures.

The fact that SemVer is rapidly catching on among purveyors of software library/components, in no way implies any kind of consensus. I would argue that it's barely made a dent, and many of the folks who do proclaim to apply it, do so less diligently than many of us would prefer.

Getting back to your OP:

To normalize/standardize the dot-separated pre-release and build identifiers, can the specification be updated to refer to the sub-components as label and id?

Probably not any time soon, particularly if no one steps forward to issue a PR with new language to that effect. Such a PR would have to include language, or be linked to a PR, proposing a good solution to the SemVer version ambiguity problem. Basically, what you are proposing is a breaking change to the standard. There are many folks out there who have their own schemes for the prerelease tag that would be out of compliance with your proposed changes, but who are in compliance with version 2.0.0 of the standard. Therefore, there must be some mechanism to disambiguate version 2+n.0.0 version strings from version 2.0.0 version strings.

If you're actually interested in this topic, take a look at VersionMeta and VersionSchema. I've been working a contract job the past year, so it's kind of stalled a bit, but I could use all the feedback/help that I can get.

@jwdonahue commented on GitHub (Oct 20, 2019): > I think it's fair to say there was no broad consensus on what a version should imply, until SemVer came into being That's a very software oriented view, and a myopic one, even within that narrow field. Version labeling of various published artifacts has been going on for thousands of years. If you bother to search, you should find a very long list of papers published/presented to various IEEE and ACM interest groups dating back decades. The DOD and DOE also have written standards/guidelines that predate SemVer by decades. I am sure that AT&T and IBM have contributed a host of "standards" as well, and I know various teams within Microsoft have their own. **Prior to SemVer, lacking any refining information, a software version label, was just that. A label indicating what version of the software it was attached to. That is still the case today**. Even version strings that are known to purport compliance with the SemVer standard, meet that minimum bar, in most but no all cases. At least that is usually the intent. We can't ignore the fact that version strings provide weak guarantees regarding the uniqueness of the versioned product. It is all too common to find packages with identical labels and differing content signatures. The fact that SemVer is rapidly catching on among purveyors of software library/components, in no way implies any kind of consensus. I would argue that it's barely made a dent, and many of the folks who do proclaim to apply it, do so less diligently than many of us would prefer. ____________ Getting back to your OP: > To normalize/standardize the dot-separated pre-release and build identifiers, can the specification be updated to refer to the sub-components as label and id? Probably not any time soon, **particularly if no one steps forward to issue a PR with new language to that effect**. Such a PR would have to include language, or be linked to a PR, proposing a good solution to the SemVer version ambiguity problem. Basically, what you are proposing is a breaking change to the standard. There are many folks out there who have their own schemes for the prerelease tag that would be out of compliance with your proposed changes, but who are in compliance with version 2.0.0 of the standard. Therefore, there must be some mechanism to disambiguate version 2+n.0.0 version strings from version 2.0.0 version strings. If you're actually interested in this topic, take a look at [VersionMeta](http://versionmeta.org/) and [VersionSchema](http://versionschema.org). I've been working a contract job the past year, so it's kind of stalled a bit, but I could use all the feedback/help that I can get.

GiteaMirror commented

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

@muzafa-popo commented on GitHub (Nov 24, 2019):

reade

@muzafa-popo commented on GitHub (Nov 24, 2019): reade

GiteaMirror commented

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

@jwdonahue commented on GitHub (Jan 10, 2020):

@zfields wrote:

To normalize/standardize the dot-separated pre-release and build identifiers, can the specification be updated to refer to the sub-components as label and id?

The answer to your question is: not without a PR. Unless you intend to issue one, or you have further questions on this subject, please close this thread at your earliest possible convenience. We've been trying to keep the list of open issues down to those that have at least some chance of leading to changes in the spec. Anyone looking for answers to questions, should be searching all issues, not just the open ones. Closing the thread does not prevent others from reading/replying to it.

@jwdonahue commented on GitHub (Jan 10, 2020): @zfields wrote: > To normalize/standardize the dot-separated pre-release and build identifiers, can the specification be updated to refer to the sub-components as label and id? The answer to your question is: not without a PR. Unless you intend to issue one, or you have further questions on this subject, please close this thread at your earliest possible convenience. We've been trying to keep the list of open issues down to those that have at least some chance of leading to changes in the spec. Anyone looking for answers to questions, should be searching all issues, not just the open ones. Closing the thread does not prevent others from reading/replying to it.

GiteaMirror commented

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

@zfields commented on GitHub (Jan 13, 2020):

We've been trying to keep the list of open issues down to those that have at least some chance of leading to changes in the spec.

To be clear, my goal would be to change the specification to consider metadata (dot-separated pre-release and build identifiers) tags, which would enable people to infer, or reason, about their meaning.

@jwdonahue you have made it quite clear that you do not believe this issue has "some chance of leading to changes in the spec". However, I would like a response from a member of the semver group.

Once I have heard a member's perspective on this matter, then I am content for this issue to be closed - if need be.

@zfields commented on GitHub (Jan 13, 2020): > We've been trying to keep the list of open issues down to those that have at least some chance of leading to changes in the spec. To be clear, my goal would be to change the specification to consider metadata (dot-separated pre-release and build identifiers) tags, which would enable people to infer, or reason, about their meaning. @jwdonahue you have made it quite clear that you do not believe this issue has _"some chance of leading to changes in the spec"_. However, I would like a response from a member of the `semver` group. Once I have heard a member's perspective on this matter, then I am content for this issue to be closed - if need be.

GiteaMirror commented

2026-06-20 17:23:46 -05:00

@jwdonahue commented on GitHub (Jan 13, 2020):

@anangaur, @dherman, @indirect, @isaacs, @segiddins, @steveklabnik, @Seldaek.

OP requests one of you to weigh-in on whether this thread should be closed.

@jwdonahue commented on GitHub (Jan 13, 2020): @anangaur, @dherman, @indirect, @isaacs, @segiddins, @steveklabnik, @Seldaek. OP requests one of you to weigh-in on whether this thread should be closed.

GiteaMirror commented

2026-06-20 17:23:46 -05:00

@Seldaek commented on GitHub (Jan 14, 2020):

I obviously speak only for myself here, but I see little chance of this happening as what various people and organizations put in the build metadata and prerelease parts of their versions can get very wild. We could for sure declare some things as valid and some as invalid semver versions, but then most likely none of the implementations would be able to strictly accept only valid versions, as there are too many invalid ones out there. Unless you are starting a brand new package ecosystem, you have to live with the reality of what's existing.

@Seldaek commented on GitHub (Jan 14, 2020): I obviously speak only for myself here, but I see little chance of this happening as what various people and organizations put in the build metadata and prerelease parts of their versions can get **very wild**. We could for sure declare some things as valid and some as invalid semver versions, but then most likely none of the implementations would be able to strictly accept only valid versions, as there are too many invalid ones out there. Unless you are starting a brand new package ecosystem, you have to live with the reality of what's existing.

GiteaMirror commented

2026-06-20 17:23:47 -05:00

@jwdonahue commented on GitHub (Jan 16, 2020):

@zfields, I recommend that you read the CONTRIBUTING.md file and consider issuing PR's to your favorite package code sites that implement your changes as experimental features, then issue an RFC. In the absence of those things, please close this issue at your earliest possible convenience.

@jwdonahue commented on GitHub (Jan 16, 2020): @zfields, I recommend that you read the [CONTRIBUTING.md](https://github.com/semver/semver/blob/master/CONTRIBUTING.md) file and consider issuing PR's to your favorite package code sites that implement your changes as experimental features, then issue an RFC. In the absence of those things, please close this issue at your earliest possible convenience.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#7369