---
title: Package Version
description: Package Version protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Package Version Protocol

A **package version** is an **immutable** release snapshot of a package.

Once published (`status = 'published'`), its `manifestJson` and `checksum`

fields are frozen — publishing is the act of sealing the snapshot.

Lifecycle:

draft → published → deprecated

Installing a package means pointing a `sys_package_installation` row at a

specific `sys_package_version` UUID. Upgrading swaps that pointer atomically.

See `docs/adr/0003-package-as-first-class-citizen.md` for the full rationale.

<Callout type="info">
**Source:** `packages/spec/src/cloud/package-version.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { CreatePackageVersionRequest, PackageManifest, PackageVersion, PackageVersionStatus, PublishPackageVersionRequest, UpdatePackageVersionRequest } from '@objectstack/spec/cloud';
import type { CreatePackageVersionRequest, PackageManifest, PackageVersion, PackageVersionStatus, PublishPackageVersionRequest, UpdatePackageVersionRequest } from '@objectstack/spec/cloud';

// Validate data
const result = CreatePackageVersionRequest.parse(data);
```

---

## CreatePackageVersionRequest

Create a new draft package version

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **packageId** | `string` | ✅ | Parent package UUID |
| **version** | `string` | ✅ | Semantic version string |
| **manifestJson** | `string` | ✅ | Initial manifest JSON (can be updated while draft) |
| **releaseNotes** | `string` | optional |  |
| **isPreRelease** | `boolean` | optional |  |
| **createdBy** | `string` | ✅ | User ID creating this version |


---

## PackageManifest

Package manifest snapshot embedded in a package version

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Package manifest ID (reverse-domain) |
| **version** | `string` | ✅ | Semver version string (e.g. 1.2.3) |
| **name** | `string` | ✅ | Display name |
| **description** | `string` | optional | Short description |
| **scope** | `Enum<'platform' \| 'environment'>` | ✅ | Package scope |
| **minPlatformVersion** | `string` | optional | Minimum required platform version (semver) |
| **dependencies** | `Object[]` | ✅ | Package dependencies |
| **metadataTypes** | `string[]` | ✅ | Metadata types provided by this package |
| **migrations** | `string[]` | ✅ | Migration script identifiers (ordered) |
| **configurationSchema** | `Record<string, any>` | optional | JSON Schema for per-installation configuration properties |
| **metadata** | `Record<string, any>` | optional | Extension metadata |


---

## PackageVersion

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | UUID of the package version (stable, never reused) |
| **packageId** | `string` | ✅ | UUID of the parent sys_package row |
| **version** | `string` | ✅ | Semantic version string |
| **status** | `Enum<'draft' \| 'published' \| 'deprecated'>` | ✅ | Package version lifecycle status |
| **manifestJson** | `string` | ✅ | JSON-serialized package manifest (frozen on publish) |
| **checksum** | `string` | optional | SHA-256 hex digest of manifestJson |
| **releaseNotes** | `string` | optional | Release notes for this version (markdown) |
| **minPlatformVersion** | `string` | optional | Minimum required platform version (denormalized from manifest) |
| **isPreRelease** | `boolean` | ✅ | Whether this is a pre-release version |
| **publishedAt** | `string` | optional | Publish timestamp (ISO-8601) |
| **publishedBy** | `string` | optional | User ID who published this version |
| **createdAt** | `string` | ✅ | Creation timestamp (ISO-8601) |
| **updatedAt** | `string` | ✅ | Last update timestamp (ISO-8601) |
| **createdBy** | `string` | ✅ | User ID that created this version |


---

## PackageVersionStatus

Package version lifecycle status

### Allowed Values

* `draft`
* `published`
* `deprecated`


---

## PublishPackageVersionRequest

Publish a draft version — seals manifestJson and checksum

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **publishedBy** | `string` | ✅ | User ID publishing this version |


---

## UpdatePackageVersionRequest

Update a draft package version (only while status is draft)

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **manifestJson** | `string` | optional | Updated manifest JSON |
| **releaseNotes** | `string` | optional |  |
| **isPreRelease** | `boolean` | optional |  |


---

