Plugin Versioning and Compatibility Protocol

Defines comprehensive versioning, compatibility checking, and dependency

resolution mechanisms for the plugin ecosystem.

Based on semantic versioning (SemVer) with extensions for:

Compatibility matrices
Breaking change detection
Migration paths
Multi-version support

Source: packages/spec/src/kernel/plugin-versioning.zod.ts

TypeScript Usage

import { BreakingChange, CompatibilityLevel, CompatibilityMatrixEntry, DependencyConflict, DeprecationNotice, MultiVersionSupport, PluginCompatibilityMatrix, PluginDependencyResolutionResult, PluginVersionMetadata, SemanticVersion, VersionConstraint } from '@objectstack/spec/kernel';
import type { BreakingChange, CompatibilityLevel, CompatibilityMatrixEntry, DependencyConflict, DeprecationNotice, MultiVersionSupport, PluginCompatibilityMatrix, PluginDependencyResolutionResult, PluginVersionMetadata, SemanticVersion, VersionConstraint } from '@objectstack/spec/kernel';

// Validate data
const result = BreakingChange.parse(data);

BreakingChange

Properties

Property	Type	Required	Description
introducedIn	`string`	✅	Version that introduced this breaking change
type	`Enum<'api-removed' \| 'api-renamed' \| 'api-signature-changed' \| 'behavior-changed' \| 'dependency-changed' \| 'configuration-changed' \| 'protocol-changed'>`	✅
description	`string`	✅
migrationGuide	`string`	optional	How to migrate from old to new
deprecatedIn	`string`	optional	Version where old API was deprecated
removedIn	`string`	optional	Version where old API will be removed
automatedMigration	`boolean`	✅	Whether automated migration tool is available
severity	`Enum<'critical' \| 'major' \| 'minor'>`	✅	Impact severity

CompatibilityLevel

Compatibility level between versions

Allowed Values

fully-compatible
backward-compatible
deprecated-compatible
breaking-changes
incompatible

CompatibilityMatrixEntry

Properties

Property	Type	Required	Description
from	`string`	✅	Version being upgraded from
to	`string`	✅	Version being upgraded to
compatibility	`Enum<'fully-compatible' \| 'backward-compatible' \| 'deprecated-compatible' \| 'breaking-changes' \| 'incompatible'>`	✅	Compatibility level between versions
breakingChanges	`Object[]`	optional
migrationRequired	`boolean`	✅
migrationComplexity	`Enum<'trivial' \| 'simple' \| 'moderate' \| 'complex' \| 'major'>`	optional
estimatedMigrationTime	`number`	optional
migrationScript	`string`	optional	Path to migration script
testCoverage	`number`	optional	Percentage of migration covered by tests

DependencyConflict

Properties

Property	Type	Required
type	`Enum<'version-mismatch' \| 'missing-dependency' \| 'circular-dependency' \| 'incompatible-versions' \| 'conflicting-interfaces'>`	✅
plugins	`Object[]`	✅
description	`string`	✅
resolutions	`Object[]`	optional
severity	`Enum<'critical' \| 'error' \| 'warning' \| 'info'>`	✅

DeprecationNotice

Properties

Property	Type	Required	Description
feature	`string`	✅	Deprecated feature identifier
deprecatedIn	`string`	✅
removeIn	`string`	optional
reason	`string`	✅
alternative	`string`	optional	What to use instead
migrationPath	`string`	optional	How to migrate to alternative

MultiVersionSupport

Properties

Property	Type	Required	Description
enabled	`boolean`	✅
maxConcurrentVersions	`integer`	✅	How many versions can run at the same time
selectionStrategy	`Enum<'latest' \| 'stable' \| 'compatible' \| 'pinned' \| 'canary' \| 'custom'>`	✅
routing	`Object[]`	optional
rollout	`Object`	optional

PluginCompatibilityMatrix

Properties

Property	Type	Required	Description
pluginId	`string`	✅
currentVersion	`string`	✅
compatibilityMatrix	`Object[]`	✅
supportedVersions	`Object[]`	✅
minimumCompatibleVersion	`string`	optional	Oldest version that can be directly upgraded

PluginDependencyResolutionResult

Properties

Property	Type	Required	Description
success	`boolean`	✅
resolved	`Object[]`	optional
conflicts	`Object[]`	optional
warnings	`string[]`	optional
installationOrder	`string[]`	optional	Plugin IDs in order they should be installed
dependencyGraph	`Record<string, string[]>`	optional	Map of plugin ID to its dependencies

PluginVersionMetadata

Properties

Property	Type	Required	Description
pluginId	`string`	✅
version	`Object`	✅	Semantic version number
versionString	`string`	✅	Full version string (e.g., 1.2.3-beta.1+build.123)
releaseDate	`string`	✅
releaseNotes	`string`	optional
breakingChanges	`Object[]`	optional
deprecations	`Object[]`	optional
compatibilityMatrix	`Object[]`	optional
securityFixes	`Object[]`	optional
statistics	`Object`	optional
support	`Object`	✅

SemanticVersion

Semantic version number

Properties

Property	Type	Required	Description
major	`integer`	✅	Major version (breaking changes)
minor	`integer`	✅	Minor version (backward compatible features)
patch	`integer`	✅	Patch version (backward compatible fixes)
preRelease	`string`	optional	Pre-release identifier (alpha, beta, rc.1)
build	`string`	optional	Build metadata