A.2.1 Examples

A single version in an npm package dependency:

• originally seen as a dependency on version "1.2.3" in a package.json manifest
• the version range spec is: vers:npm/1.2.3

A list of versions, enumerated:

• vers:pypi/0.0.0|0.0.1|0.0.2|0.0.3|1.0|2.0pre1

A complex statement about a vulnerability in a "maven" package that affects multiple branches each with their own fixed versions at https://repo1.maven.org/maven2/org/apache/tomee/apache-tomee/ Note how the constraints are sorted:

• "affects Apache TomEE 8.0.0-M1 - 8.0.1, Apache TomEE 7.1.0 - 7.1.2, Apache TomEE 7.0.0-M1 - 7.0.7, Apache TomEE 1.0.0-beta1 - 1.7.5."
• a normalized version range spec is: vers:maven/>=1.0.0-beta1|<=1.7.5|>=7.0.0-M1|<=7.0.7|>=7.1.0|<=7.1.2|>=8.0.0-M1|<=8.0.1
• alternatively, four vers express the same range, using one vers for each vulnerable "branches":
  • vers:tomee/>=1.0.0-beta1|<=1.7.5
  • vers:tomee/>=7.0.0-M1|<=7.0.7
  • vers:tomee/>=7.1.0|<=7.1.2
  • vers:tomee/>=8.0.0-M1|<=8.0.1

Converting RubyGems custom syntax for dependency on gem. Note how the pessimistic version constraint is expanded:

• 'library', '~> 2.2.0', '!= 2.2.1'
• the version range spec is: vers:gem/>=2.2.0|!= 2.2.1|<2.3.0

A.2.2 URI scheme

The vers URI scheme is an acronym for "VErsion Range Specifier". It has been selected because it is short, obviously about version and available for a future formal registration for this URI-scheme at the IANA registry.

The URI scheme is followed by a colon ":".

<versioning-scheme>

The <versioning-scheme> (such as npm, deb, etc.) determines:

• the specific notation and conventions used for a version string encoded in this scheme. Versioning schemes often specify a version segments separator and the meaning of each version segment, such as [major.minor.patch] in semver.
• how two versions are compared as greater or lesser to determine if a version is within or outside a range.
• how a versioning scheme-specific range notation can be transformed in the vers simplified notation defined here.

By convention the versioning scheme should be the same as the Package-URL package type for a given package ecosystem. It is OK to have other schemes beyond the purl type. A scheme could be specific to a single package name.

The <versioning-scheme> is followed by a slash "/".

A.2.3 <version-constraint>

After the <versioning-scheme> and "/" there are one or more <version-constraint> separated by a pipe "|". The pipe "|" has no special meaning beside being a separator.

Each <version-constraint> of this list is either a single <version> as in 1.2.3 for example or the combination of a <comparator> and a <version> as in >=2.0.0 using this syntax:

<comparator><version>

A single version means that a version equal to this version satisfies the range spec. Equality is based on the equality of two normalized version strings according to their versioning scheme. For most schemes, this is a simple string equality. But schemes can specify normalization and rules for equality such as pypi with PEP440.

The special star "*" comparator matches any version. It must be used alone exclusive of any other constraint and must not be followed by a version. For example "vers:deb/*" represents all the versions of a Debian package. This includes past, current and possible future versions.

Otherwise, the <comparator> is one of these comparison operators:

• "!=": Version exclusion or inequality comparator. This means a version must not be equal to the provided version that must be excluded from the range. For example: "!=1.2.3" means that version "1.2.3" is excluded.
• "<", "<=": Lesser than or lesser-or-equal version comparators point to all versions less than or equal to the provided version. For example "<=1.2.3" means less than or equal to "1.2.3".
• ">", ">=": Greater than or greater-or-equal version comparators point to all versions greater than or equal to the provided version. For example ">=1.2.3" means greater than or equal to "1.2.3".

The <versioning-scheme> defines:

• how to compare two version strings using these comparators, and
• the structure of a version string such as "1.2.3" if any. For instance, the semver specification for version numbers defines a version as composed primarily of three dot-separated numeric segments named major, minor and patch.

A.4.1 Version constraints simplification

Tools can simplify a list of <version-constraint> using this approach:

These pairs of contiguous constraints with these comparators are valid:

• != followed by anything
• =, <, or <= followed by =, !=, >, or >=
• >, or >= followed by !=, <, or <=

These pairs of contiguous constraints with these comparators are redundant and invalid (ignoring any != since they can show up anywhere):

• =, < or <= followed by < or <=: this is the same as < or <=
• > or >= followed by =, > or >=: this is the same as > or >=

A procedure to remove redundant constraints can be:

• Start from a list of constraints of comparator and version, sorted by version and where each version occurs only once in any constraint.
• If the constraints list contains a single constraint (star, equal or anything) return this list and simplification is finished.
• Split the constraints list in two sub lists:
  • a list of "unequal constraints" where the comparator is "!="
  • a remainder list of "constraints" where the comparator is not "!="
• If the remainder list of "constraints" is empty, return the "unequal constraints" list and simplification is finished.
• Iterate over the constraints list, considering the current and next contiguous constraints, and the previous constraint (e.g., before current) if it exists:
  • If current comparator is ">" or ">=" and next comparator is "=", ">" or ">=", discard next constraint
  • If current comparator is "=", "<" or "<=" and next comparator is <" or <=", discard current constraint. Previous constraint becomes current if it exists.
  • If there is a previous constraint:
    • If previous comparator is ">" or ">=" and current comparator is "=", ">" or ">=", discard current constraint
    • If previous comparator is "=", "<" or "<=" and current comparator is <" or <=", discard previous constraint
• Concatenate the "unequal constraints" list and the filtered "constraints" list
• Sort by version and return.

A.4.2 Checking if a version is contained within a range

To check if a "tested version" is contained within a version range:

• Start from a parsed a version range specifier with:
  • a versioning scheme
  • a list of constraints of comparator and version, sorted by version and where each version occurs only once in any constraint.
• If the constraint list contains only one item and the comparator is "*", then the "tested version" is IN the range. Check is finished.
• Select the version equality and comparison procedures suitable for this versioning scheme and use these for all version comparisons performed below.
• If the "tested version" is equal to the any of the constraint versions where the constraint comparator is for equality (any of "=", "<=", or ">=") then the "tested version" is in the range. Check is finished.
• If the "tested version" is equal to the any of the constraint versions where the constraint comparator is "=!" then the "tested version" is NOT in the range. Check is finished.
• Split the constraint list in two sub lists:
  • a first list where the comparator is "=" or "!="
  • a second list where the comparator is neither "=" nor "!="
• Iterate over the current and next contiguous constraints pairs (aka. pairwise) in the second list.
• For each current and next constraint:
  • If this is the first iteration and current comparator is "<" or <=" and the "tested version" is less than the current version then the "tested version" is IN the range. Check is finished.
  • If this is the last iteration and next comparator is ">" or >=" and the "tested version" is greater than the next version then the "tested version" is IN the range. Check is finished.
  • If current comparator is ">" or >=" and next comparator is "<" or <=" and the "tested version" is greater than the current version and the "tested version" is less than the next version then the "tested version" is IN the range. Check is finished.
  • If current comparator is "<" or <=" and next comparator is ">" or >=" then these versions are out the range. Continue to the next iteration.
• Reaching here without having finished the check before means that the "tested version" is NOT in the range.

A.4.3 Notes and caveats

• Comparing versions from two different versioning schemes is an error. Even though there may be some similarities between the semver version of an npm and the deb version of its Debian packaging, the way versions are compared specific to each versioning scheme and may be different. Tools should report an error in this case.
• All references to sorting or ordering of version constraints means sorting by version. And sorting by versions always implies using the versioning scheme-specified version comparison and ordering.

A.8.1 Why not use the OSV Ranges?

See:

• https://ossf.github.io/osv-schema/

vers and the OSSF OSV schema vulnerable ranges are equivalent and vers provides a compact range notation while OSV provides a more verbose JSON notation.

vers borrows the design from and was informed by the OSV schema spec and its authors.

OSV uses a minimalist set of only three comparators:

• "=" to enumerate versions,
• ">=" for the version that introduced a vulnerability, and
• "<" for the version that fixed a vulnerability.

OSV Ranges support neither ">" nor "!=" comparators making it difficult to express some ranges that must exclude a version. This may not be an issue for most vulnerable ranges yet:

• this makes it difficult or impossible to precisely express certain dependency and vulnerable ranges when a version must be excluded and the set of existing versions is not yet known,
• this make some ranges more verbose such as with the CVE v5 API ranges notation that can include their upper limit and would need two constraints.

Another high level difference between the two specifications is the codes used to qualify a range package "ecosystem" value that resembles closely the Package-URL package "type" used in vers. This spec will provide a strict mapping between the OSV ecosystem and the vers versioning schemes values.

A.8.2 Why not use the CVE v5 API Ranges?

See:

• https://github.com/CVEProject/cve-schema/blob/master/schema/v5.0/CVE_JSON_5.0_schema.json#L303
• https://github.com/CVEProject/cve-schema/blob/master/schema/v5.0/CVE_JSON_5.0_schema.json#L123

The version 5 of the CVE JSON data format defines version ranges with a starting version, a versionType, and an upper limit for the version range as lessThan or lessThanOrEqual or as an enumeration of versions. The versionType and the package collectionURL possible values are only indicative and left out of this specification and both seem strictly equivalent to the Package-URL "type" on the one hand and thevers versioning scheme on the other hand.

The semantics and expressiveness of each range are similar and vers provides a compact notation rather than a more verbose JSON notation. vers supports strictly the conversion of any CVE v5 range to its notation and further provides a concrete list of well known versioning schemes. vers design was informed by the CVE v5 API schema spec and its authors.

When CVE v5 becomes active, this spec will provide a strict mapping between the CVE versionType and the vers versioning schemes values. Furthermore, this spec and the Package-URL "types" should be updated accordingly to provide a mapping with the upcoming CVE collectionURL that will be effectively used.

There is one issue with CVE v5: it introduces a new trailing "*" notation that does not exist in most version ranges notations and may not be computable easily in many cases. The description of the "lessThan" property is:

The non-inclusive upper limit of the range. This is the least version NOT in the range. The usual version syntax is expanded to allow a pattern to end in an asterisk (), indicating an arbitrarily large number in the version ordering. For example, {version: 1.0 lessThan: 1.} would describe the entire 1.X branch for most range kinds, and {version: 2.0, lessThan: *} describes all versions starting at 2.0, including 3.0, 5.1, and so on.

The conversion to vers range should be:

• with a version 1.0 and "lessThan": "*", the vers equivalent is: >=1.0.
• with a version 1.0 and "lessThan": "2.*", the vers equivalent can be computed for semver versions as >=1.0|<2 but this is not accurate because the versioning schemes have different rules. For instance, pre-release may be treated in some case as part of the v1. branch and in some other cases as part of the v2. branch. It is not clear if with "2.*" the CVE v5 spec means:
  • <2
  • or something that excludes any version string that starts with 2.

And in this case, with the expression "lessThan": "2.*" using a semver version, it is not clear if 2.0.0-alpha is "lessThan"; semver sorts it before 2.0 and after 1.0, e.g., in semver 2.0.0-alpha is "less than" 2.

A.8.3 Why not use the NVD CPE Ranges?

See:

• https://nvd.nist.gov/vuln/vulnerability-detail-pages#divRange
• https://nvd.nist.gov/developers/vulnerabilities#divResponse
• https://csrc.nist.gov/schema/nvd/feed/1.1/nvd_cve_feed_json_1.1.schema

The version ranges notation defined in the JSON schema of the CVE API payload uses these four fields: versionStartIncluding, versionStartExcluding, versionEndIncluding and versionEndExcluding. For example:

"versionStartIncluding": "7.3.0",
"versionEndExcluding": "7.3.31",
"versionStartExcluding" : "9.0.0",
"versionEndIncluding" : "9.0.46",

In addition to these ranges, the NVD publishes a list of concrete CPEs with versions resolved for a range with daily updates at https://nvd.nist.gov/vuln/data-feeds#cpeMatch

Note that the NVD CVE configuration is a complex specification that goes well beyond version ranges and is used to match comprehensive configurations across multiple products and version ranges. vers focus is exclusively versions.

In contrast with vers compact notation, the NVD JSON notation is more verbose, yet vers supports strictly the conversion of any CPE range.

A.8.4 Why not use node-semver ranges?

See:

• https://github.com/npm/node-semver#ranges

The node-semver spec is similar to but much more complex than this spec. This is an AND of ORs constraints with a few practical issues:

• A space means "AND", therefore white spaces are significant. Having significant white spaces in a string makes normalization more complicated and may be a source of confusion if you remove the spaces from the string. vers avoids the ambiguity of spaces by ignoring them.
• The advanced range syntax has grown to be rather complex using hyphen ranges, stars ranges, carets and tilde constructs that are all tied to the JavaScript and npm ways of handling versions in their ecosystem and are bound furthermore to the semver semantics and its npm implementation. These are not readily reusable elsewhere. The multiple comparators and modifiers make the notation grammar more complex to parse and process for a machine and harder to read for human.

Notations that are directly derived from node-semver as used in Rust and PHP Composer have the same issues.

A.8.5 Why not use Python PEP-0440 ranges?

See:

• https://www.python.org/dev/peps/pep-0440/#version-specifiers

The Python pep-0440 "Version Identification and Dependency Specification" provides a comprehensive specification for Python package versioning and a notation for "version specifiers" to express the version constraints of dependencies.

This specification is similar to this vers spec, with more operators and aspects specific to the versions used only in the Python ecosystem.

• In particular pep-0440 uses tilde, triple equal and wildcard star operators that are specific to how two Python versions are compared.
• The comma separator between constraints is a logical "AND" rather than an "OR". The "OR" does not exist in the syntax making some version ranges harder to express, in particular for vulnerabilities that may affect several exact versions or ranges for multiple parallel release branches. Ranges such as "Django 1.2 or later, or Django 2.2 or later or Django 3.2 or later" are difficult to express without an "OR" logic.

A.8.6 Why not use RubyGems requirements notation?

See:

• https://guides.rubygems.org/patterns/#declaring-dependencies

The RubyGems specification suggests but does not enforce using semver. It uses operators similar to the node-semver spec with the difference of the ">" aka. pessimistic operator vs. a plain "" tilde used in node-semver. This operator implies some semver-like versioning, yet gem versions are not strictly semver. This makes the notation complex to implement and impractical to reuse in places that do not use the same Ruby-specific semver-like semantics.

A.8.7 Why not use fewer comparators with only =, >= and <?

For instance, the OSV schema adopts a reduced set of only three comparators:

• "=" is implied when used to enumerate vulnerable versions
• ">=" (greater or equal) is for the version that introduces a vulnerability
• "<" (lesser) is for the version that fixes a vulnerability

This approach is simpler and works well for most vulnerable ranges but it faces limitations when converting from other notations:

• ">" cannot be converted reliably to ">=" unless you know all the versions and these will never change.
• "<=" cannot be converted reliably to "<" unless you know all the versions and these will never change.
• "!=" cannot be converted reliably: there is no ">" comparator to create an unequal equivalent of "><"; and a combo of ">=" and "<" is not equivalent to inequality unless you know all the versions and these will never change.

A.8.8 Why not use richer comparators such as tilde, caret and star?

Some existing notations such as used with npm, gem, python, or composer provide syntactic shorthand such as:

• a "pessimistic operator" using tilde, > or = as in "1.3" or ">1.2.3"
• a caret ^ prefix as in "^ 1.2"
• using a star in a version segment as in "1.2.*"
• dash-separated ranges as in "1.2 - 1.4"
• arbitrary string equality such as "===1.2"

Most of these notations can be converted without loss to the vers notation. Furthermore these notations typically assume a well defined version string structure specific to their package ecosystem and are not reusable in another ecosystem that would not use the exact same version conventions.

For instance, the tilde and caret notations demand that you can reliably infer the next version (aka. "bump") from a given version; this is possible only if the versioning scheme supports this operation reliably for all its accepted versions.

A.8.9 Why not use mathematical interval notation for ranges?

Apache Maven and NuGet use a mathematical interval notation with comma-separated "[", "]", "(" and ")" to declare version ranges.

All other known range notations use the more common ">", "<", and "=" as comparators. vers adopts this familiar approach.