Version Meta

Version: Experimental.0 {VSchemaInDev.0}


Version Meta is a proposed standard tag for version strings. The tag is meant to convey both; human and machine readable information, regarding the location of the version schema used to build the version string. All version meta tags will be enclosed in curly braces {} and MUST always immediately precede or follow a version string conforming to the specified schema. See for details on the proposed schema DOM. The version listed near the top of this page is an example of a well-known schema tag, that tooling can use to lookup the named schema (service location is TBD).


There are many packaging schemes in use today that each; either have their own versioning scheme, or varying levels of adherence to some specified standard, such as one version or another of Semantic Versioning. Currently only context and format analysis distinguishes them from each other. Consider the following version strings:

  1. "1"
  2. "1.0"
  3. "1.0.0"
  4. ""

Depending on the context, #1 might just be an abbreviation referring to any of the others. #2 could also be an abbreviation of #'s 3 or 4, but its format could also imply that it is a tuple version number of some unknown pedigree. #3 may be the most pernicious, as it appears that it may conform to any of SemVer's specification versions, and the version triple is probably the most common format in use, so one cannot assume it's a SemVer string based on the triple. #4 could be almost anything. None of them tell us anything about the logic, if any, that was applied to generate the version.

Most versioning schemes give us some relief in the form of meta tags, such as prerelease labels or build meta-data. If we understand the language that the tags derive from, we can make some assumptions about the relative quality of each version of a particular product. Only rarely can we apply such logic to different products satisfying similar needs, because we know nothing of the processes applied by the varying product developers. Consider the following:

One might suspect that the UberSkyLib product is a stable, shipping product and HyperSkyLib is obviously experimental, so perhaps we should investigate UberSkyLib as a candidate for inclusion in our product? Other than the implied goodness of the RC1 tag, and the fact there are no leading zeroes in the version number, we really have no reason at all to suspect that UberSkyLib is any more stable than HyperSkyLib. Even if we know they both adhere to Semantic Versioning, we still don't know anything about their relative development practices. Without digging into both of them using ad-hoc research methods, all we can do is guess. It could be that HyperSkyLib is based off of UberSkyLib 1.0.0 and that their 93 versions are a couple of hundred fewer than UberSkyLib. The standards and methods of each product team cannot be known from the version label, and the contexts within which version labels are found; rarely have obvious linkage to those standards and methods.

The proposed solution to these and other issues around package version labels, is to promote the use of the Version Meta tag, to provide a standard method for obtaining the necessary information we need, to make critical judgements regarding the expected quality of a given release. I propose that a Version Schema standard be developed and evolve to satisfy the needs of the developer and consumer communities. The Version Meta standard will only address the content, formats and locations of the Version Meta tag, not the Version Schema.

Version Meta Specification (VersionMeta)

The key-words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. The phrase "Version Meta tag" used herein, refers to tags used to specify a URI to a Version Schema ({}), or a well-known identifier ({SimpleCounter}), and should not be confused with other meta tags, that may be specified by various version schemes (Build Meta used in SemVer for instance).

1. All version Meta tags MUST be expressed as UTF-8 code sequences.

2. All Version Meta tags MUST begin with an opening curly brace '{', which MUST be followed by a URI, which MUST be followed by a closing curly brace '}'.

TBD: Right to left languages?

TBD: Different/Alternate delimiters?

3. Version Meta tags MUST NOT contain any whitespace, between the URI or well-known identifier, and the opening and closing currly braces.

4. There MUST NOT be more than one Version Meta tag associated with any version string.

5. Version Meta tags SHOULD be placed on the same line as their respective version strings.

6. Version Meta tags SHOULD follow their respective version strings.

7. Version Meta tags MUST be within plus or minus one line of their respective version strings.

8. Version Meta tags MAY precede or follow their respective version strings.

9. When multiple product version strings are displayed in close proximity, such as a list or table, the associated Version Meta tags MUST be displayed with a consistent relative position to their respective version strings.

10. All Version Meta tags MUST resolve to a Version Schema as defined by


Why Use Version Meta?

Because you want your customers to understand your versioning scheme. When your customers don't grok your release versioning policies, you burn a lot of customer support cycles and so do they. Because you are proud of your processes and confident it will benefit both you and your customers.

Widespread adoption of Version Meta tags, will allow automation to properly reason over dependency graphs and pull required updates with less risk to your software development projects. It allows flexibility in processes, avoiding the use of lowest common demonitor standards. It's the next step from Semantic Versioning, on the road out of dependency hell.


The Version Meta specification is originally authored by me, Joseph W Donahue. I am looking forward to collaborating with anyone who has a contribution to make to this effort.


This document is licensed, as-per the LICENSE file, as derived from the MIT License. The original condition:

"The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software"

was changed to:

"The above copyright notice, a clear indication whether the content has been modified, and this permission notice shall be included in all copies or substantial portions of the Software".

In other words, MIT + tell everyone whether you simply copied the content or modified it.


Last updated 2020-02-05 11:00 UTC