ObjectStackVersioning
Versioning protocol schemas
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)
Source: packages/spec/src/api/versioning.zod.ts
TypeScript Usage
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);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 | { version: string; status: Enum<'preview' | 'current' | 'supported' | 'deprecated' | 'retired'>; releasedAt: string; deprecatedAt?: string; … }[] | optional | Full version definitions with lifecycle metadata |
VersionStatus
Allowed Values
previewcurrentsupporteddeprecatedretired
VersioningConfig
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| strategy | Enum<'urlPath' | 'header' | 'queryParam' | 'dateBased'> | ✅ | 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 | ✅ | HTTP header name for version negotiation (header/dateBased strategies) |
| queryParamName | string | ✅ | Query parameter name for version specification (queryParam strategy) |
| urlPrefix | string | ✅ | URL prefix before version segment (urlPath strategy) |
| deprecation | { warnHeader: boolean; sunsetHeader: boolean; linkHeader: boolean; rejectRetired: boolean; … } | optional | Deprecation lifecycle behavior |
| includeInDiscovery | boolean | ✅ | Include version information in the API discovery endpoint |
VersioningStrategy
Allowed Values
urlPathheaderqueryParamdateBased