Skip to main content
AI•Pkg uses Semantic Versioning 2.0.0 (SemVer 2.0.0) for all package versions. This document is the normative versioning specification.

​
SemVer 2.0.0 Compliance

All AI•Pkg versions must be valid SemVer 2.0.0 strings. The full specification is at semver.org. All three components are required. Shorthand is not accepted:

​
Pre-Release Versions

Versions with a pre-release identifier (the - suffix) are recognized as pre-release:
Pre-release identifiers are not enforced — any SemVer-valid pre-release string is accepted. The values above are recognized conventions that affect UI labeling.
Pre-release versions are:
  • Hidden from search results unless prerelease=true is passed
  • Listed below stable versions on the package detail page
  • Installable explicitly by specifying the full version string

​
Build Metadata

Build metadata (the + suffix) is:
  • Stored by the registry verbatim
  • Stripped for version comparison (two versions differing only in build metadata are equal)
  • Not indexed — +build.42 is not searchable

​
Version Normalization

The registry applies normalization at push time. Normalized versions are stored and returned in all API responses.

​
Dependency Version Ranges

Dependency version constraints in .aispec use NuGet version range notation: Version ranges are resolved client-side by the aipkg CLI using the version list from GET /v3/flatcontainer/{id}/index.json.

​
Version Ordering

Versions are ordered as follows:
  1. Release versions sort by major, minor, patch (numeric, descending for “latest”)
  2. Pre-release versions sort below the corresponding release version
  3. Pre-release identifiers are compared per SemVer rules:
    • Numeric identifiers are compared numerically: rc.2 > rc.1
    • Alphanumeric identifiers are compared lexically: rc > beta > alpha (alphabetically)
    • Numeric identifiers always have lower precedence than alphanumeric: 1 < alpha
Example ordering (highest to lowest):

​
Immutability

Published versions cannot be overwritten. A push of an id+version combination that already exists returns 409 Conflict. The only mechanism to prevent a version from being installed is unlisting (DELETE /v3/package/{id}/{version}), which sets listed: false. Unlisted versions:
  • Remain in the registry and can be downloaded by explicit version reference
  • Do not appear in search results or version lists by default
  • Cannot be physically deleted at MVP
There is no physical delete at MVP. Unlisting is the only way to hide a version from normal user flows.