ObjectStackObjectStack
ReferenceKernel Protocol

Plugin Versioning — Kernel Protocol reference

Defines comprehensive versioning, compatibility checking, and dependency resolution mechanisms for the plugin ecosystem.

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 { BreakingChangeSchema, CompatibilityLevelSchema, CompatibilityMatrixEntrySchema, DependencyConflictSchema, DeprecationNoticeSchema, MultiVersionSupportSchema, PluginCompatibilityMatrixSchema, PluginDependencyResolutionResultSchema, PluginVersionMetadataSchema, SemanticVersionSchema, VersionConstraintSchema } 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 = BreakingChangeSchema.parse(data);

BreakingChange

Properties

PropertyTypeRequiredDescription
introducedInstring✅Version that introduced this breaking change
typeEnum<'api-removed' | 'api-renamed' | 'api-signature-changed' | 'behavior-changed' | 'dependency-changed' | 'configuration-changed' | 'protocol-changed'>✅
descriptionstring✅
migrationGuidestringoptionalHow to migrate from old to new
deprecatedInstringoptionalVersion where old API was deprecated
removedInstringoptionalVersion where old API will be removed
automatedMigrationbooleanoptional (default: false)Whether automated migration tool is available
severityEnum<'critical' | 'major' | 'minor'>✅Impact severity

CompatibilityLevel

Compatibility level between versions

Allowed Values

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

CompatibilityMatrixEntry

Properties

PropertyTypeRequiredDescription
fromstring✅Version being upgraded from
tostring✅Version being upgraded to
compatibilityEnum<'fully-compatible' | 'backward-compatible' | 'deprecated-compatible' | 'breaking-changes' | 'incompatible'>✅Compatibility level between versions
breakingChanges{ introducedIn: string; type: Enum<'api-removed' | 'api-renamed' | 'api-signature-changed' | 'behavior-changed' | …>; description: string; migrationGuide?: string; … }[]optional
migrationRequiredbooleanoptional (default: false)
migrationComplexityEnum<'trivial' | 'simple' | 'moderate' | 'complex' | 'major'>optional
estimatedMigrationTimeHoursnumberoptionalEstimated migration time in hours
estimatedMigrationTimeneveroptional[REMOVED] CompatibilityMatrixEntry.estimatedMigrationTime was renamed to estimatedMigrationTimeHours in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in prose. Rename the key to estimatedMigrationTimeHours; the value (hours) is unchanged.
migrationScriptstringoptionalPath to migration script
testCoveragenumberoptionalPercentage of migration covered by tests

Nested Shape: CompatibilityMatrixEntry.breakingChanges[number]

PropertyTypeRequiredDescription
introducedInstring✅Version that introduced this breaking change
typeEnum<'api-removed' | 'api-renamed' | 'api-signature-changed' | 'behavior-changed' | …>✅
descriptionstring✅
migrationGuidestringoptionalHow to migrate from old to new
deprecatedInstringoptionalVersion where old API was deprecated
removedInstringoptionalVersion where old API will be removed
automatedMigrationbooleanoptional (default: false)Whether automated migration tool is available
severityEnum<'critical' | 'major' | 'minor'>✅Impact severity

DependencyConflict

Properties

PropertyTypeRequiredDescription
typeEnum<'version-mismatch' | 'missing-dependency' | 'circular-dependency' | 'incompatible-versions' | 'conflicting-interfaces'>✅
plugins{ pluginId: string; version: string; requirement?: string }[]✅
descriptionstring✅
resolutions{ strategy: Enum<'upgrade' | 'downgrade' | 'replace' | 'disable' | 'manual'>; description: string; automaticResolution?: boolean; riskLevel: Enum<'low' | 'medium' | 'high'> }[]optional
severityEnum<'critical' | 'error' | 'warning' | 'info'>✅

Nested Shape: DependencyConflict.plugins[number]

PropertyTypeRequiredDescription
pluginIdstring✅
versionstring✅
requirementstringoptionalWhat this plugin requires

DeprecationNotice

Properties

PropertyTypeRequiredDescription
featurestring✅Deprecated feature identifier
deprecatedInstring✅
removeInstringoptional
reasonstring✅
alternativestringoptionalWhat to use instead
migrationPathstringoptionalHow to migrate to alternative

MultiVersionSupport

Properties

PropertyTypeRequiredDescription
enabledbooleanoptional (default: false)
maxConcurrentVersionsintegeroptional (default: 2)How many versions can run at the same time
selectionStrategyEnum<'latest' | 'stable' | 'compatible' | 'pinned' | 'canary' | 'custom'>optional (default: "latest")
routing{ condition: string | object; version: string; priority?: integer }[]optional
rollout{ enabled?: boolean; strategy: Enum<'percentage' | 'blue-green' | 'canary'>; percentage?: number; durationMs?: integer }optional

Nested Shape: MultiVersionSupport.routing[number]

PropertyTypeRequiredDescription
conditionstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }✅Routing predicate (CEL).
versionstring✅Version to use when condition matches
priorityintegeroptional (default: 100)Rule priority

Nested Shape: MultiVersionSupport.rollout

PropertyTypeRequiredDescription
enabledbooleanoptional (default: false)
strategyEnum<'percentage' | 'blue-green' | 'canary'>✅
percentagenumberoptionalPercentage of traffic to new version
durationMsintegeroptionalRollout duration in milliseconds
durationneveroptional[REMOVED] MultiVersionSupport.rollout.duration was renamed to durationMs in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose. Rename the key to durationMs; the value (milliseconds) is unchanged.

PluginCompatibilityMatrix

Properties

PropertyTypeRequiredDescription
pluginIdstring✅
currentVersionstring✅
compatibilityMatrix{ from: string; to: string; compatibility: Enum<'fully-compatible' | 'backward-compatible' | 'deprecated-compatible' | …>; breakingChanges?: object[]; … }[]✅
supportedVersions{ version: string; supported: boolean; endOfLife?: string; securitySupport?: boolean }[]✅
minimumCompatibleVersionstringoptionalOldest version that can be directly upgraded

Nested Shape: PluginCompatibilityMatrix.compatibilityMatrix[number]

PropertyTypeRequiredDescription
fromstring✅Version being upgraded from
tostring✅Version being upgraded to
compatibilityEnum<'fully-compatible' | 'backward-compatible' | 'deprecated-compatible' | …>✅Compatibility level between versions
breakingChanges{ introducedIn: string; type: Enum<'api-removed' | 'api-renamed' | 'api-signature-changed' | 'behavior-changed' | …>; description: string; migrationGuide?: string; … }[]optional
migrationRequiredbooleanoptional (default: false)
migrationComplexityEnum<'trivial' | 'simple' | 'moderate' | 'complex' | 'major'>optional
estimatedMigrationTimeHoursnumberoptionalEstimated migration time in hours
estimatedMigrationTimeneveroptional[REMOVED] CompatibilityMatrixEntry.estimatedMigrationTime was renamed to estimatedMigrationTimeHours in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in prose. Rename the key to estimatedMigrationTimeHours; the value (hours) is unchanged.
migrationScriptstringoptionalPath to migration script
testCoveragenumberoptionalPercentage of migration covered by tests

Nested Shape: PluginCompatibilityMatrix.supportedVersions[number]

PropertyTypeRequiredDescription
versionstring✅
supportedboolean✅
endOfLifestringoptionalEnd of support date
securitySupportbooleanoptional (default: false)Still receives security updates

PluginDependencyResolutionResult

Properties

PropertyTypeRequiredDescription
successboolean✅
resolved{ pluginId: string; version: string; resolvedVersion: string }[]optional
conflicts{ type: Enum<'version-mismatch' | 'missing-dependency' | 'circular-dependency' | …>; plugins: object[]; description: string; resolutions?: object[]; … }[]optional
warningsstring[]optional
installationOrderstring[]optionalPlugin IDs in order they should be installed
dependencyGraphRecord<string, string[]>optionalMap of plugin ID to its dependencies

PluginVersionMetadata

Properties

PropertyTypeRequiredDescription
pluginIdstring✅
version{ major: integer; minor: integer; patch: integer; preRelease?: string; … }✅Semantic version number
versionStringstring✅Full version string (e.g., 1.2.3-beta.1+build.123)
releaseDatestring✅
releaseNotesstringoptional
breakingChanges{ introducedIn: string; type: Enum<'api-removed' | 'api-renamed' | 'api-signature-changed' | 'behavior-changed' | …>; description: string; migrationGuide?: string; … }[]optional
deprecations{ feature: string; deprecatedIn: string; removeIn?: string; reason: string; … }[]optional
compatibilityMatrix{ from: string; to: string; compatibility: Enum<'fully-compatible' | 'backward-compatible' | 'deprecated-compatible' | …>; breakingChanges?: object[]; … }[]optional
securityFixes{ cve?: string; severity: Enum<'critical' | 'high' | 'medium' | 'low'>; description: string; fixedIn: string }[]optional
statistics{ downloads?: integer; installations?: integer; ratings?: number }optional
support{ status: Enum<'active' | 'maintenance' | 'deprecated' | 'eol'>; endOfLife?: string; securitySupport?: boolean }✅

Nested Shape: PluginVersionMetadata.version

PropertyTypeRequiredDescription
majorinteger✅Major version (breaking changes)
minorinteger✅Minor version (backward compatible features)
patchinteger✅Patch version (backward compatible fixes)
preReleasestringoptionalPre-release identifier (alpha, beta, rc.1)
buildstringoptionalBuild metadata

Nested Shape: PluginVersionMetadata.breakingChanges[number]

PropertyTypeRequiredDescription
introducedInstring✅Version that introduced this breaking change
typeEnum<'api-removed' | 'api-renamed' | 'api-signature-changed' | 'behavior-changed' | …>✅
descriptionstring✅
migrationGuidestringoptionalHow to migrate from old to new
deprecatedInstringoptionalVersion where old API was deprecated
removedInstringoptionalVersion where old API will be removed
automatedMigrationbooleanoptional (default: false)Whether automated migration tool is available
severityEnum<'critical' | 'major' | 'minor'>✅Impact severity

Nested Shape: PluginVersionMetadata.deprecations[number]

PropertyTypeRequiredDescription
featurestring✅Deprecated feature identifier
deprecatedInstring✅
removeInstringoptional
reasonstring✅
alternativestringoptionalWhat to use instead
migrationPathstringoptionalHow to migrate to alternative

Nested Shape: PluginVersionMetadata.compatibilityMatrix[number]

PropertyTypeRequiredDescription
fromstring✅Version being upgraded from
tostring✅Version being upgraded to
compatibilityEnum<'fully-compatible' | 'backward-compatible' | 'deprecated-compatible' | …>✅Compatibility level between versions
breakingChanges{ introducedIn: string; type: Enum<'api-removed' | 'api-renamed' | 'api-signature-changed' | 'behavior-changed' | …>; description: string; migrationGuide?: string; … }[]optional
migrationRequiredbooleanoptional (default: false)
migrationComplexityEnum<'trivial' | 'simple' | 'moderate' | 'complex' | 'major'>optional
estimatedMigrationTimeHoursnumberoptionalEstimated migration time in hours
estimatedMigrationTimeneveroptional[REMOVED] CompatibilityMatrixEntry.estimatedMigrationTime was renamed to estimatedMigrationTimeHours in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in prose. Rename the key to estimatedMigrationTimeHours; the value (hours) is unchanged.
migrationScriptstringoptionalPath to migration script
testCoveragenumberoptionalPercentage of migration covered by tests

Nested Shape: PluginVersionMetadata.securityFixes[number]

PropertyTypeRequiredDescription
cvestringoptionalCVE identifier
severityEnum<'critical' | 'high' | 'medium' | 'low'>✅
descriptionstring✅
fixedInstring✅Version where vulnerability was fixed

SemanticVersion

Semantic version number

Properties

PropertyTypeRequiredDescription
majorinteger✅Major version (breaking changes)
minorinteger✅Minor version (backward compatible features)
patchinteger✅Patch version (backward compatible fixes)
preReleasestringoptionalPre-release identifier (alpha, beta, rc.1)
buildstringoptionalBuild metadata

VersionConstraint

Union Options

This schema accepts one of the following structures:

Option 1

Exact version: 1.2.3

Type: string

Option 2

Compatible with: ^1.2.3 (>=1.2.3 <2.0.0)

Type: string

Option 3

Approximately: ~1.2.3 (>=1.2.3 <1.3.0)

Type: string

Option 4

Greater than or equal: >=1.2.3

Type: string

Option 5

Greater than: >1.2.3

Type: string

Option 6

Less than or equal: <=1.2.3

Type: string

Option 7

Less than: <1.2.3

Type: string

Option 8

Range: 1.2.3 - 2.3.4

Type: string

Option 9

Any version

Type: '*'

Option 10

Latest stable version

Type: 'latest'

Plugin Security Advanced

Defines comprehensive security mechanisms for plugin isolation, permission management, and threat protection in the ObjectStack ecosystem.

Package Artifact

Defines the standard structure of a package artifact (.tgz) produced by the build pipeline.

On this page

Plugin Versioning and Compatibility ProtocolTypeScript UsageBreakingChangePropertiesCompatibilityLevelAllowed ValuesCompatibilityMatrixEntryPropertiesNested Shape: CompatibilityMatrixEntry.breakingChanges[number]DependencyConflictPropertiesNested Shape: DependencyConflict.plugins[number]DeprecationNoticePropertiesMultiVersionSupportPropertiesNested Shape: MultiVersionSupport.routing[number]Nested Shape: MultiVersionSupport.rolloutPluginCompatibilityMatrixPropertiesNested Shape: PluginCompatibilityMatrix.compatibilityMatrix[number]Nested Shape: PluginCompatibilityMatrix.supportedVersions[number]PluginDependencyResolutionResultPropertiesPluginVersionMetadataPropertiesNested Shape: PluginVersionMetadata.versionNested Shape: PluginVersionMetadata.breakingChanges[number]Nested Shape: PluginVersionMetadata.deprecations[number]Nested Shape: PluginVersionMetadata.compatibilityMatrix[number]Nested Shape: PluginVersionMetadata.securityFixes[number]SemanticVersionPropertiesVersionConstraintUnion OptionsOption 1Option 2Option 3Option 4Option 5Option 6Option 7Option 8Option 9Option 10