Draft ECMA-xxx

1st Edition / December 6, 2026

Version Range Specifier (VERS) specification

About this specification

The document at https://tc54.org/vers/ is the most accurate and up-to-date VERS specification.

This document is available as a single page and as multiple pages.

Contributing to this specification

This specification is developed on GitHub with the help of the VERS community. There are a number of ways to contribute to the development of this specification:

Refer to the colophon for more information on how this document was created.

Introduction

There is no universal notation for software package version ranges and there is no universal way to compare two versions of a package even though the concepts in many version range notations are similar. Each package type or ecosystem may define its own version range notation and version comparison semantics for dependencies.

For security advisories, the lack of a portable and compact notation for vulnerable package version ranges means that these ranges may be ambiguous or hard to compute and may be replaced by complete enumerations of all impacted versions. Expressing and resolving a version range is often a complex and error prone task because of the ambiguity and the use of enumerations of impacted versions is an approach that may require frequent updates. A version range is a necessary, compact, and practical way to reference multiple versions rather than listing all versions.

Version Range Specifier (VERS) introduces a standard URI-based syntax to define package version ranges and the semantics (algorithm or procedure) to interpret each version range notation. This standardization provides more accurate and consistent analysis of package version dependencies and the impact of known vulnerabilities or bugs on a package. VERS was developed in concert with the Package-URL (PURL) specification standardized with ECMA-427.

Challenges addressed by VERS:

As software supply chain security becomes a global priority, formalizing VERS as an international standard supports its adoption and consistent implementation. Standardization under Ecma International Technical Committee 54 (TC54) positions VERS as a foundational building block for secure, transparent, and efficient software ecosystems worldwide.

By enabling a universally recognized and implementable specification, VERS aligns with global efforts to improve the security, reliability, and accountability of software supply chains. Its adoption ensures that organizations and developers can rely on a common way to specify and interpret package version ranges for managing package dependency resolution and software vulnerability analysis and mitigation.

This Ecma Standard was developed by Technical Committee 54 and was adopted by the General Assembly of December 2026.

1 Scope

This Standard defines the Version Range Specifier (VERS) syntax for specifying a software version range notation as a compact alternative to enumerating a list of software versions. The primary use cases for VERS are identifying software package versions that are impacted by a vulnerability and analyzing software package version dependencies.

A VERS notation is a valid URI composed of two components to identify a software package. The VERS type component defines the ecosystem-specific structure and meaning for the VERS constraints component. This Standard specifies the syntax for VERS and the schema for defining VERS types, but it does not include any specific VERS type definitions.

This edition of the Standard supports linear versioning where the software versions do not branch to form a tree of versions. For tree-based versioning with branches, a possible solution is to use multiple VERS until direct support for tree use cases is implemented in a future version of the Standard.

2 Conformance

A conforming implementation of the Version Range Specifier (VERS) Standard shall fully implement and support all elements defined within this Standard, including the syntax, components, and semantic requirements for constructing and interpreting valid VERS notations.

A conforming implementation of VERS shall adhere to the syntax defined in this Standard, ensuring that all VERS notations are constructed, parsed, and validated according to the prescribed rules. The implementation shall provide full support for ecosystem-agnostic behaviour, enabling VERS to function consistently and reliably across diverse environments.

All required components of a VERS notation - scheme, type, and constraints - shall be present and validated according to the rules defined in this Standard.

Implementations shall ensure that equivalent VERS notations are consistently resolved to the same canonical representation. This includes strict adherence to normalization and equivalence rules. Furthermore, implementations shall process URI encoding and decoding for VERS components according to the standards outlined in RFC 3986.

Invalid VERS notations that fail to conform to the Standard shall be identified and rejected by any conforming implementation. This guarantees the integrity and reliability of VERS notations in all supported contexts.

A conforming implementation of VERS may extend its functionality by providing ecosystem-specific validation, processing, or metadata handling, as long as these extensions do not violate the core specification. Additionally, implementations may offer auxiliary tools or features, such as utilities for constructing or validating VERS notations, provided they align with the Standard's requirements.

A conforming implementation shall not redefine or alter the core syntax, components, or semantics defined by this Standard. Any prohibited extensions explicitly identified in the specification shall not be implemented. Furthermore, behaviours that compromise the interoperability of VERS across tools, platforms, or ecosystems are strictly disallowed.

The verbal forms in this Standard follow ISO/IEC Directives, Part 2: shall and shall not indicate requirements; should and should not indicate recommendations; may and need not indicate permission; and can and cannot indicate possibility or capability. The verbal form must is used only for external constraints and does not express a requirement of this Standard.

3 Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

RFC 3986, Uniform Resource Identifier (URI): Generic Syntax
https://datatracker.ietf.org/doc/html/rfc3986

The Unicode Standard
https://www.unicode.org/versions/latest/

4 Overview informative

This Clause contains a non-normative overview of the VERS specification.

The Version Range Specifier (VERS) Standard defines a lightweight and compact URI-based syntax for specifying software package version ranges. VERS provides a practical alternative to enumerating all versions for common use cases like identifying package versions impacted by a vulnerability or analyzing package dependencies. VERS also defines the semantics (algorithm or procedure) to interpret each VERS notation.

This Standard focuses on the core aspects of VERS, including its syntax, required components, optional attributes, and conformance requirements. VERS is complementary to the Package-URL (PURL) Standard ECMA-427.

The primary audience for this Standard includes developers, tool implementers, and organizations involved in software composition analysis, dependency management, and supply chain security.

While this document serves as the authoritative reference for implementing VERS, it is complemented by various ecosystem-specific guidance documents, examples, and related standards. These resources provide additional context and practical insights for leveraging VERS effectively.

This overview is non-normative and serves to provide context for the intent, purpose, and audience for the Standard. For detailed requirements and conformance criteria, refer to the normative clauses of this Standard.

5 VERS Specification

VERS stands for "Version Range Specifier". A VERS is an ASCII URI string composed of three components:

    
      scheme:type/constraints

When there are multiple constraints, they are separated by an unencoded pipe '|'.

Components are separated by a specific character for unambiguous parsing.

Table 1: Components of a VERS
Component Requirement Description
scheme Required The URI scheme with the constant value of 'vers'.
type Required The Version Range Specifier type such as 'deb', 'npm', 'pypi' 'semver' etc.
constraints Required A sequence of one or more version ranges.

This edition of the VERS Standard only applies to linear versioning use cases; it does not cover tree-based versioning use cases. To model branching trees of versions, a possible solution is to use multiple VERS, one for each branch.

5.1 A VERS is a URI scheme

A VERS is a valid URI scheme that conforms to URI definitions or specifications at: https://tools.ietf.org/html/rfc3986.

Example 1 (Informative): Node Package Manager
vers:npm/1.2.3|>=2.0.0|<5.0.0
Example 2 (Informative): Ruby Gem
vers:gem/>=2.2.0|!=2.2.1|<2.3.0

5.2 Separator characters

This is how each of the separator characters is used:

  • ':' (colon) is the separator between scheme and type.
  • '/' (slash) is the separator between type and constraints.
  • '|' (pipe) is the separator between segments of `constraints`.

5.3 Rules for each VERS component

5.3.1 Scheme

  • The scheme is a constant with the value "vers".
  • The scheme shall be followed by an unencoded colon ':'.

5.3.2 Type

  • The type shall be composed only of ASCII letters and numbers, period '.', and dash '-'.
  • The type shall start with an ASCII letter.
  • The type shall not be percent-encoded.
  • The type is case insensitive and lowercase.
  • The type shall be followed by a slash '/'.

A type defines:

  • the specific notation and conventions used for constraints encoded according to this type;
  • how a type-specific range notation shall be transformed into VERS constraints;
  • how two versions are compared to determine if a version is inside or outside a range;
  • how to compare two version strings using comparators;
  • the structure of a version string such as "1.2.3". For example, the "semver" specification for version numbers defines a version as composed primarily of three dot-separated numeric segments named "major", "minor" and "patch".

By convention a type should be the same as the PURL type for a given package or software ecosystem. It is, however, permissible to define a type that does not match an existing PURL type such as a VERS type that applies to a single package or project or a general purpose version scheme like 'semver'.

This Standard includes the VERS Type Definition Schema but it does not include the set of current "registered" VERS type definition files (JSON format) because there are ongoing additions and changes to these files. The current "registered" VERS type definition files are located at: https://www.packageurl.org/vers-types/. Registration refers to the Package-URL community process for adding a new VERS type.

There are two rules related to the set of registered VERS type definitions for conforming tools to validate the VERS type component:

  • If a VERS type is registered, then a VERS is invalid if it does not conform to all of the rules for the corresponding VERS type definition.
  • If a VERS type is not registered, then the type component is valid if it conforms to the rules stated in the type component rules in this Clause of the Standard. In this case tools should report a warning that the VERS type is not registered.

5.3.3 Constraints

  • The constraints component shall be preceded by an unencoded '/' slash separator and shall contain one or more constraints.
  • Each segment of the constraints component is called a constraint. Each constraint is composed of either a single version as in '1.2.3' or the combination of a comparator and a version as in '>=2.0.0'.
  • A comparator always precedes the version with no characters allowed between the comparator and the version.
  • Multiple constraints segments shall be separated by an unencoded pipe '|'. The pipe "|" has no special meaning other than being a separator.
  • There is no limit on the number of constraints segments.

The sequence of constraints represents distinct intervals in the version timeline of a package. The separators do not mean "and" or "or". They are separators in a sequence of constraints segments.

5.3.3.1 Comparators

A comparator is composed of these ASCII characters:

  • the Equals character: '=' (equals, '=')
  • the Not Equals character: '!' (exclamation mark, '!')
  • the Greater Than character: '>' (greater than, '>')
  • the Less Than character: '<' (less than, '<')
  • the Asterisk character: '*' (asterisk, '*')

A comparator shall be one of the following:

  • null is the Equality comparator and the default. For example, 'vers:npm/1.2.3 means that the version is equal to "1.2.3". If a constraint` string starts with '=', tools shall report an error.
  • '!=' is the Inequality comparator. This means that a version shall not be equal to the provided version and it shall be excluded from the range. For example: '!=1.2.3' means that version "1.2.3" is excluded.
  • '<' is the Less-than comparator. This includes all versions less than the provided version.
  • '<=': is the Less-or-equal comparator. This includes all versions less than or equal to the provided version. For example '<=1.2.3' means less than or equal to "1.2.3".
  • '>' is the Greater-than comparator. This includes all versions greater than the provided version.
  • '>=' is the Greater-or-equal comparator. This includes 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 special Asterisk '*' comparator matches any version. It shall be used alone and exclusive of any other comparator and shall not be followed by a version. For example, 'vers:deb/*' represents all versions of a Debian package. This includes past, current and possible future versions.

5.3.3.2 Version

A version is an ASCII string.

  • A version contains only printable ASCII letters, digits and punctuation.
  • If a version contains any of these characters: '>', '<', '=', '!', '*', '|', '%', these characters shall be percent-encoded using URI percent-encoding rules.
  • ASCII whitespace is not permitted in a VERS string except for a percent-encoded space ('%20'). Tools shall report an error if any other ASCII whitespace character, for example tab or line feed, is used. Percent-encoding is applied to the literal version data: a literal '%' in a version shall be encoded as '%25', while the '%' that starts an existing percent-encoded triplet shall not be encoded again.
  • Tools shall report an error for invalid percent-encoded sequences.

A single version in a constraint means that a package version equal to this version satisfies the range specification. Equality is based on the equality of two normalized version strings according to the applicable VERS type. For most schemes, this is a simple string equality. A type may, however, define normalization or other rules for equality such as the "pypi" rules from PEP 440.

A package version satisfies VERS constraints if it is contained within any of the segments defined by the constraints.

5.4 VERS validation rules

VERS validation rules are designed such that a VERS notation is easy for a human to read and understand, and straightforward for tools to process. The rules are also designed to prevent the creation of empty or impossible version ranges. These rules are:

  • Constraints shall be sorted by version order. The ordering of the constraints segments is significant for validity: tools shall report an error for invalid ordering.
  • Versions are unique. Each version shall be unique within a constraints instance, and shall occur only once in any constraint, regardless of the comparators. Tools shall report an error for duplicated versions.
  • There shall be only one asterisk in a constraints sequence: Asterisk ('*') shall occur only once and alone in a constraints instance. An Asterisk constraint shall not be used with other constraints in a Constraints sequence.

Starting from a de-duplicated and sorted list of constraints, the following rules apply to the comparators of any two contiguous constraints segments:

  • A constraint using the '!=' comparator shall be followed by a constraint using a comparator (any of null, '!=', '>', '>=', '<', '<=') or (no constraint).
  • Ignoring all constraints with the '!=' comparator, a null (equality) constraint shall be followed only by a constraint with one of: null, '>', or '>=' (or no constraint).
  • Ignoring all constraints with the '!=' comparator or the null (equality) comparator, the sequence of constraints shall be an alternation of Greater-than and Lesser-than comparators:
    • A constraint using '<' or '<=' shall be followed by one of '>' or '>=' (or no constraint).
    • A constraint using '>' or '>=' shall be followed by one of '<' or '<=' (or no constraint).

Tools shall report an error for an invalid sequence of constraints segments.

6 VERS Type Definition Schema

The VERS Type Definition JSON Schema is the reference data model that is used to define VERS types in a structured way. Each VERS type is specified in a JSON document that matches this schema. These JSON documents are then used to generate VERS type documentation and to support VERS tools and libraries so that they can more easily build, parse, and validate PURLs by type in a consistent and standardized manner across programming languages and technology stacks.

6.1 JSON Schema

The VERS Type Definition Schema is formally specified by a Draft 2020-12 JSON Schema. Each published version of this specification is accompanied by a versioned meta-schema at a stable URI:

https://packageurl.org/vers-schemas/vers-type-definition.schema-<major>.<minor>.json

Location: /

Type: Object

Schema to specify a Version Range Specifier (VERS) type as a structured definition.

Table 2: Properties for the root object
Property Type Requirement Description
type String Required The type string for this VERS type.
type_name String Required The name for this VERS type.
description String Required The description of this VERS type.
vers_examples Array Required Examples for valid VERS ranges for this VERS type.
native_range_and_vers_equivalent_examples Array Optional List of examples of valid, native version ranges mapped to their corresponding VERS syntax.
note String Optional Note about this VERS type.
reference_urls Array Optional List of informational reference URLs about this VERS type, such as specifications or reference code.

6.2 VERS type

Location: /type

Property: type (Required)

Type: String

Pattern Constraint: ^[a-z][a-z0-9-\.]+$

The type string for this VERS type.

Example 1 (Informative): Maven
maven
Example 2 (Informative): Node Package Manager
npm
Example 3 (Informative): Python Package Index
pypi

6.3 Type name

Location: /type_name

Property: type_name (Required)

Type: String

The name for this VERS type.

Example 1 (Informative): Maven
Apache Maven Dependency Version Requirement
Example 2 (Informative): Node Package Manager
npm version range

6.4 Description

Location: /description

Property: description (Required)

Type: String

The description of this VERS type.

6.5 VERS examples

Location: /vers_examples

Property: vers_examples (Required)

Type: Array (of String)

Pattern Constraint: ^vers:[a-z][a-z0-9-\.]+/.*$

Examples of valid VERS ranges for this VERS type.

All items shall be unique.

6.6 Native range and VERS equivalent examples

Location: /native_range_and_vers_equivalent_examples

Property: native_range_and_vers_equivalent_examples (Optional)

Type: Object

The definition of native and VERS range equivalents for a VERS type. This information is optional for a VERS type.

Table 3: Properties for the native_range_and_vers_equivalent_examples object
Property Type Requirement Description
native_range String Required Native range example for this VERS type.
vers String Required Corresponding VERS notation for this VERS type.
note String Optional Optional note about this example.
reference_url URI as specified in RFC 3986 Optional Optional reference URL for this native range example.

6.7 Note

Location: /note

Property: note (Optional)

Type: String

Note about this VERS type.

6.8 Reference URLs

Location: /reference_urls

Property: reference_urls (Optional)

Type: array (of String)

Format: URI as specified in RFC 3986

Optional list of informational reference URLs about this VERS type. Each item of this array shall be a string.

All items shall be unique.

Annex A (normative) VERS Type Definition

This Annex provides a copy of the current Version Range Specifier (VERS) Type Definition Schema. The format is JSON Schema version Draft 2020-12.

The schema shown below is available in electronic form at: https://packageurl.org/vers-schemas/vers-type-definition.schema-1.0.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema#",
  "$id": "https://packageurl.org/vers-schemas/vers-type-definition.schema-1.0.json",
  "title": "Version Range Specifier (VERS) Type Definition",
  "description": "Schema to define the structure of a VErsion Range Specifier (VERS) type.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "$id",
    "type",
    "type_name",
    "description",
    "vers_examples"
  ],
  "properties": {
    "$schema": {
      "title": "JSON schema",
      "description": "URL of the JSON schema for VERS type definition.",
      "const": "https://packageurl.org/vers-schemas/vers-type-definition.schema-1.0.json",
      "format": "uri"
    },
    "$id": {
      "title": "VERS type definition id",
      "description": "The unique identifier URI for this VERS type definition.",
      "type": "string",
      "pattern": "^https:\\/\\/packageurl\\.org/vers-types/[a-z0-9-]+-definition\\.json$"
    },
    "type": {
      "title": "VERS type",
      "description": "The type string for this VERS type.",
      "type": "string",
      "pattern": "^[a-z][a-z0-9-\\.]+$",
      "examples": [
        "semver",
        "maven",
        "pypi",
        "npm"
      ]
    },
    "type_name": {
      "title": "Type name",
      "description": "The name of this VERS type.",
      "type": "string",
      "examples": [
        "Apache Maven Dependency Version Requirement",
        "npm version range"
      ]
    },
    "description": {
      "title": "Description",
      "description": "The description of this VERS type.",
      "type": "string",
      "examples": [
        "Apache Maven dependency version requirement as defined in a Maven POM.",
        "npm dependencies version range as defined in a package.json.",
        "RubyGems version requirement restrictions using restriction operators."
      ]
    },
    "vers_examples": {
      "title": "VERS examples",
      "description": "Examples of valid VERS notations for this VERS type.",
      "type": "array",
      "uniqueItems": true,
      "minItems": 1,
      "items": {
        "type": "string",
        "pattern": "^vers:[a-z][a-z0-9-\\.]+/.*$"
      },
      "examples": [
        [
          "vers:npm/1.223",
          "vers:semver/<1.2.2|>2.0.0|=7.0.0"
        ]
      ]
    },
    "native_range_and_vers_equivalent_examples": {
      "title": "Examples of native version ranges and their VERS equivalents.",
      "description": "Optional list of examples of native version ranges mapped to their corresponding VERS syntax.",
      "type": "array",
      "uniqueItems": true,
      "minItems": 1,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "native_range",
          "vers"
        ],
        "properties": {
          "native_range": {
            "title": "Native range example",
            "description": "Native range example for this VERS type.",
            "type": "string"
          },
          "vers": {
            "title": "Corresponding VERS notation",
            "description": "Corresponding VERS notation for this VERS type.",
            "type": "string"
          },
          "note": {
            "title": "Note",
            "description": "Optional note about this example.",
            "type": "string"
          },
          "reference_url": {
            "title": "Reference URL",
            "description": "Optional reference URL for this native range example.",
            "type": "string",
            "format": "uri"
          }
        }
      }
    },
    "note": {
      "title": "Note",
      "description": "Note about this VERS type.",
      "type": "string"
    },
    "reference_urls": {
      "title": "Reference URLs",
      "description": "List of informational reference URLs about this VERS type, such as specifications or reference code.",
      "type": "array",
      "uniqueItems": true,
      "minItems": 1,
      "items": {
        "type": "string",
        "format": "uri"
      },
      "examples": [
        "https://maven.apache.org/pom.html#dependency-version-requirement-specification",
        "https://github.com/npm/node-semver",
        "https://docs.npmjs.com/cli/v12/configuring-npm/package-json#dependencies",
        "https://github.com/ruby/ruby/blob/d1c079751b80352d347452c8d134ffb177838adb/lib/rubygems/requirement.rb#L6"
      ]
    }
  }
}

Bibliography

Colophon

This Standard is authored on GitHub in a plaintext source format called Ecmarkup. Ecmarkup is an HTML and Markdown dialect that provides a framework and toolset for authoring ECMA specifications in plaintext and processing the specification into a full-featured HTML rendering that follows the editorial conventions for this document. Ecmarkup builds on and integrates a number of other formats and technologies including Grammarkdown for defining syntax and Ecmarkdown for authoring algorithm steps. PDF renderings of this Standard are produced using a print stylesheet which takes advantage of the CSS Paged Media specification and is converted using PrinceXML.

We extend our gratitude to TC39 for their exceptional work in developing Ecmarkup, which has greatly facilitated TC54's successful adoption of this tool for the preparation and maintenance of our technical specifications.

Copyright & Software License

Ecma International

Rue du Rhone 114

CH-1204 Geneva

Tel: +41 22 849 6000

Fax: +41 22 849 6001

Web: https://ecma-international.org/

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.