Versioning schema — API Protocol reference
Defines how API versions are negotiated between client and server. Supports multiple versioning strategies and deprecation lifecycle management.
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)
Source: packages/spec/src/api/versioning.zod.ts
import { VersionDefinitionSchema, VersionNegotiationResponseSchema, VersionStatus, VersioningConfigSchema, VersioningStrategy } from '@objectstack/spec/api';
import type { VersionDefinition, VersionNegotiationResponse, VersionStatus, VersioningConfig, VersioningStrategy } from '@objectstack/spec/api';
// Validate data
const result = VersionDefinitionSchema.parse(data);
| 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) |
| 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 | { version: string; status: Enum<'preview' | 'current' | 'supported' | 'deprecated' | 'retired'>; releasedAt: string; deprecatedAt?: string; … }[] | optional | Full version definitions with lifecycle metadata |
| 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) |
previewcurrentsupporteddeprecatedretired
| Property | Type | Required | Description |
|---|
| strategy | Enum<'urlPath' | 'header' | 'queryParam' | 'dateBased'> | optional (default: "urlPath") | How the API version is specified by clients |
| current | string | ✅ | The current/recommended API version identifier |
| default | string | ✅ | Fallback version when client does not specify one |
| versions | { version: string; status: Enum<'preview' | 'current' | 'supported' | 'deprecated' | 'retired'>; releasedAt: string; deprecatedAt?: string; … }[] | ✅ | All available API versions with lifecycle metadata |
| headerName | string | optional (default: "ObjectStack-Version") | HTTP header name for version negotiation (header/dateBased strategies) |
| queryParamName | string | optional (default: "version") | Query parameter name for version specification (queryParam strategy) |
| urlPrefix | string | optional (default: "/api") | URL prefix before version segment (urlPath strategy) |
| deprecation | { warnHeader?: boolean; sunsetHeader?: boolean; linkHeader?: boolean; rejectRetired?: boolean; … } | optional | Deprecation lifecycle behavior |
| includeInDiscovery | boolean | optional (default: true) | Include version information in the API discovery endpoint |
| 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) |
| Property | Type | Required | Description |
|---|
| warnHeader | boolean | optional (default: true) | Include Deprecation header (RFC 8594) in responses |
| sunsetHeader | boolean | optional (default: true) | Include Sunset header (RFC 8594) with retirement date |
| linkHeader | boolean | optional (default: true) | Include Link header pointing to migration guide URL |
| rejectRetired | boolean | optional (default: true) | Return 410 Gone for retired API versions |
| warningMessage | string | optional | Custom warning message for deprecated version responses |
urlPathheaderqueryParamdateBased
ObjectStack