Skip to main content
Every AI•Pkg package has an ID — a globally unique, immutable string that identifies the package across all versions. This document defines the normative rules for package IDs and display names.

​
Package ID Syntax

A package ID must conform to the following rules:
  • Pattern: ^[a-z][a-z0-9\-\.]{0,127}$
  • Max length: 128 characters
  • First character: lowercase ASCII letter (a–z)
  • Remaining characters: lowercase ASCII letters, digits (0–9), hyphens (-), or dots (.)
  • Case: all lowercase; uppercase is never accepted

​
Allowed Characters

​
Forbidden Patterns

Even if the character set is valid, the following patterns are rejected:

​
Reserved IDs

The following IDs (and IDs matching these prefixes) are permanently reserved and cannot be registered: A push attempting to use a reserved ID receives 400 Bad Request with error code ID_RESERVED.

​
Publisher Scoping Conventions

AI•Pkg does not enforce namespacing at the syntax level — there is no @scope/name mechanism. Instead, publishers use two conventions:

​
Prefix convention

Use a consistent prefix separated by a hyphen:

​
Dot-group convention

Use dots to create an implicit hierarchy:
Both conventions are just that — conventions. The registry does not parse or enforce them. Enforcement happens through prefix reservations (see Prefix Reservations), which give verified publishers exclusive use of a prefix.

​
Display Names vs IDs

If title is absent, the UI falls back to displaying id. Examples:

​
ID Immutability and Transfer

Once a package version is published:
  • The id cannot be changed — it is permanent for the life of the package
  • The id cannot be reused after a package is deleted — deleted IDs are tombstoned and permanently reserved
  • ID ownership can be transferred between registry accounts via a registry team support request

​
Tombstone Policy

When a package is deleted (not just unlisted), its ID is permanently reserved. A subsequent push with the same ID from any account receives 409 Conflict with error code ID_TOMBSTONED. This prevents dependency confusion attacks where a deleted package ID is re-registered with malicious content.

​
Validation Error Codes

The following error codes are returned by the registry and by AipkgValidator (see SDK Interface):