---
title: Versioning
description: Versioning protocol schemas
---

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

# API Versioning Protocol

Defines how API versions are negotiated between client and server.

Supports multiple versioning strategies and deprecation lifecycle management.

Architecture Alignment:

- Salesforce: URL path versioning (v57.0, v58.0)

- Stripe: Date-based versioning (2024-01-01)

- Kubernetes: API group versioning (v1, v1beta1)

- GitHub: Accept header versioning (application/vnd.github.v3+json)

- Microsoft Graph: URL path versioning (v1.0, beta)

<Callout type="info">
**Source:** `packages/spec/src/api/versioning.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { VersionDefinition, VersionNegotiationResponse, VersionStatus, VersioningStrategy } from '@objectstack/spec/api';
import type { VersionDefinition, VersionNegotiationResponse, VersionStatus, VersioningStrategy } from '@objectstack/spec/api';

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

---

## VersionDefinition

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **version** | `string` | ✅ | Version identifier (e.g., "v1", "v2beta1", "2025-01-01") |
| **status** | `Enum<'preview' \| 'current' \| 'supported' \| 'deprecated' \| 'retired'>` | ✅ | Lifecycle status of this version |
| **releasedAt** | `string` | ✅ | Release date (ISO 8601, e.g., "2025-01-15") |
| **deprecatedAt** | `string` | optional | Deprecation date (ISO 8601). Only set for deprecated/retired versions |
| **sunsetAt** | `string` | optional | Sunset date (ISO 8601). After this date, the version returns 410 Gone |
| **migrationGuide** | `string` | optional | URL to migration guide for upgrading from this version |
| **description** | `string` | optional | Human-readable description or release notes summary |
| **breakingChanges** | `string[]` | optional | List of breaking changes (for preview/new versions) |


---

## VersionNegotiationResponse

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **current** | `string` | ✅ | Current recommended API version |
| **requested** | `string` | optional | Version requested by the client |
| **resolved** | `string` | ✅ | Resolved API version for this request |
| **supported** | `string[]` | ✅ | All supported version identifiers |
| **deprecated** | `string[]` | optional | Deprecated version identifiers |
| **versions** | `Object[]` | optional | Full version definitions with lifecycle metadata |


---

## VersionStatus

### Allowed Values

* `preview`
* `current`
* `supported`
* `deprecated`
* `retired`


---

## VersioningStrategy

### Allowed Values

* `urlPath`
* `header`
* `queryParam`
* `dateBased`


---

