# Plugin Versioning Strategies and Update Mechanisms for OpenAI Plugins

> Learn OpenAI plugin versioning strategies and update mechanisms. Discover how semantic versioning, SDK pinning, and workflow versioning ensure safe updates and backward compatibility.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: best-practices
- Published: 2026-06-27

---

**OpenAI plugins implement a multi-layered versioning architecture that combines semantic manifest versioning, SDK dependency pinning, and workflow-level versioning to guarantee safe updates and backward compatibility across the Codex-plugin ecosystem.**

OpenAI plugins are distributed as **Codex-plugin bundles** that contain a mandatory manifest file and optional skill implementations. Understanding the plugin versioning strategies and update mechanisms for OpenAI plugins is critical for developers who need to maintain compatibility while evolving their functionality. The `openai/plugins` repository defines five complementary versioning layers that interact during development, validation, and runtime to prevent breaking changes.

## The Five Layers of Plugin Versioning

The repository structures versioning into five distinct layers, each controlling a different aspect of the plugin lifecycle.

### Plugin Manifest Version

The **plugin manifest version** controls the overall bundle definition, including the plugin name, description, required scopes, and skill inventory. This version uses semantic versioning (`MAJOR.MINOR.PATCH`) and is declared in the mandatory [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file. According to the repository root README, every plugin must reside under `plugins/<name>/` and include this manifest file.

### API (SDK) Version

The **API (SDK) version** specifies the underlying SDK that the plugin code expects, such as Zoom's `@zoom/appssdk` pinned to `^0.16.26`. This layer prevents runtime failures by ensuring the host environment provides compatible APIs. The Zoom SDK migration documentation in [`plugins/zoom/skills/zoom-apps-sdk/troubleshooting/migration.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/zoom-apps-sdk/troubleshooting/migration.md) demonstrates how the `version` field in the `config()` method enforces these constraints.

### Skill and Language Versioning

Individual **skill implementations** may evolve independently using language-specific strategies. For Temporal-based workflows, developers use **worker versioning** to handle logic changes without breaking in-flight executions. The Temporal core versioning guide in [`plugins/temporal/skills/temporal-developer/references/core/versioning.md`](https://github.com/openai/plugins/blob/main/plugins/temporal/skills/temporal-developer/references/core/versioning.md) outlines three approaches: pinning, patching via `GetVersion`, and worker versioning.

### Data and Asset Versioning

**Data resources** use incremental versioning to ensure consistency during updates. For example, Wix catalog items use integer or UUID-based versioning stored alongside asset metadata. The Wix catalog documentation in [`plugins/wix/skills/wix-manage/references/stores/query-products-catalog-v1.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-manage/references/stores/query-products-catalog-v1.md) explains how previous versions must be retained to support rollback operations.

### Marketplace Manifest Validation

The **marketplace validation layer** ensures submitted manifests match the current schema before acceptance. The validation endpoint `POST /marketplace/apps/manifest/validate` checks for schema mismatches and stale API references. This mechanism is documented in the Zoom REST API reference at [`plugins/zoom/skills/rest-api/references/marketplace-apps.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/rest-api/references/marketplace-apps.md).

## How the Versioning Layers Interact

These five layers operate sequentially across the plugin lifecycle to ensure safe distribution and execution.

1. **Development** – Developers create a new bundle by updating [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) with a new `manifest_version` and ensuring the `api_version` matches the SDKs used in skill code.

2. **CI Validation** – Before publishing, continuous integration runs the **manifest validator** against the `POST /marketplace/apps/manifest/validate` endpoint. This catches missing required fields or incompatible SDK references.

3. **Marketplace Ingestion** – The marketplace stores each manifest as a **versioned artifact**, creating immutable versions while retaining previous releases. This enables rollbacks and side-by-side testing.

4. **Runtime Drift Handling** – Clients query the manifest at startup. If the client's SDK version is older than the manifest's `api_version`, the SDK reports a drift warning and falls back to legacy keys where required, as documented in [`plugins/zoom/skills/virtual-agent/references/versioning-and-drift.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/virtual-agent/references/versioning-and-drift.md).

5. **Update Propagation** – When a new version publishes, the marketplace notifies installed instances via webhook or polling. Clients download updated manifests respecting **compatibility constraints** defined in fields like `unsupportedApis`.

## Key Update Mechanisms

The repository implements specific mechanisms to enforce these versioning strategies during updates.

### Manifest Validation Endpoint

The marketplace provides a validation endpoint that verifies manifests comply with the current schema before acceptance. This prevents drift between the production definition and submitted plugins.

### Automated CI Pipelines

Build workflows such as `npx wix build && npx wix generate manifest` or `npm run lint && npm run test` catch version mismatches early in the development cycle, as implemented in the Wix build workflow.

### Worker Versioning for Temporal

When workflow definitions change, developers increment versions in the workflow code. The Temporal server uses `GetVersion` to route in-flight executions to the appropriate handler, ensuring non-breaking updates.

### SDK Version Pinning

Zoom apps embed SDK versions in the `config()` call, causing the client to refuse execution if the installed SDK does not satisfy the required version. This is visible throughout the Zoom SDK examples where `version: '0.16'` appears frequently.

### Catalog Versioning for Wix

The Wix API exposes `GET /catalog/version` endpoints, allowing plugins to fetch the latest catalog snapshot before modifying data, preventing conflicts during concurrent updates.

## Code Examples

### Bumping the Plugin Manifest Version

Update the semantic version in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to signal a new release:

```json
{
  "name": "my-awesome-plugin",
  "description": "A demo plugin for OpenAI",
  "manifest_version": "1.2.0",
  "api_version": "2.0.0",
  "skills": [
    "skills/example-skill"
  ]
}

```

*Source: Repository root README defining the required manifest schema.*

### Pinning an SDK Version in Zoom

Explicitly declare SDK compatibility in the application configuration:

```javascript
import { ZoomApp } from '@zoom/appssdk';

ZoomApp.config({
  version: '0.16',
  clientId: process.env.ZOOM_CLIENT_ID,
  // additional configuration
});

```

*Source: Zoom SDK examples in [`plugins/zoom/skills/zoom-apps-sdk/examples/quick-start.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/zoom-apps-sdk/examples/quick-start.md).*

### Temporal Workflow Versioning

Use `Workflow.getVersion` to handle logic changes without breaking existing executions:

```typescript
import { proxyActivities, proxySignal, Workflow } from '@temporalio/workflow';

export const VERSION = {
  MY_WORKFLOW: 2,
};

export const myWorkflow = Workflow.define('my-workflow', async () => {
  const version = Workflow.getVersion('my-workflow', 1, VERSION.MY_WORKFLOW);
  if (version === 1) {
    // legacy logic
  } else {
    // current logic
  }
});

```

*Source: Temporal versioning documentation in [`plugins/temporal/skills/temporal-developer/references/core/versioning.md`](https://github.com/openai/plugins/blob/main/plugins/temporal/skills/temporal-developer/references/core/versioning.md).*

### Checking Wix Catalog Version Before Updates

Verify catalog consistency before modifying product data:

```javascript
import fetch from 'node-fetch';

async function updateProduct(productId, data) {
  const catalogRes = await fetch('https://www.wixapis.com/stores/v1/catalog/version');
  const { version } = await catalogRes.json();

  await fetch(`https://www.wixapis.com/stores/v1/products/${productId}`, {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'Wix-Catalog-Version': version,
    },
    body: JSON.stringify(data),
  });
}

```

*Source: Wix catalog versioning guide in [`plugins/wix/skills/wix-manage/references/stores/query-products-catalog-v1.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-manage/references/stores/query-products-catalog-v1.md).*

## Summary

OpenAI plugins employ a comprehensive versioning strategy that spans multiple layers of the architecture:

- **Semantic manifest versioning** in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) controls the overall bundle release cycle.
- **SDK pinning** prevents runtime failures by enforcing minimum API versions in host environments.
- **Worker versioning** allows Temporal workflows to evolve without breaking in-flight executions.
- **Data versioning** ensures consistency across catalog updates and asset modifications.
- **Marketplace validation** guarantees schema compliance before distribution through automated endpoints.

## Frequently Asked Questions

### How does the OpenAI plugins repository prevent breaking changes during updates?

The repository implements a **multi-layered validation system** that includes CI manifest validation, semantic versioning requirements, and runtime drift detection. Before any update reaches the marketplace, the `POST /marketplace/apps/manifest/validate` endpoint verifies schema compliance. During runtime, clients check the `api_version` field against installed SDKs and report drift warnings if incompatibilities are detected.

### What is the difference between manifest version and API version in OpenAI plugins?

The **manifest version** (`manifest_version`) uses semantic versioning to track the overall plugin bundle state, including metadata and skill definitions. The **API version** (`api_version`) specifies the minimum SDK version required by the plugin code. While the manifest version changes with every plugin release, the API version only changes when the plugin adopts new SDK features or breaking changes.

### How do Temporal-based plugins handle workflow updates without losing state?

Temporal plugins use **worker versioning** through the `GetVersion` API. When workflow logic changes, developers increment a version identifier in the code. The Temporal server compares this against running executions, routing existing workflows to the old logic while directing new executions to the updated code. This allows seamless updates without terminating active workflows.

### Where should developers store version information in a Codex-plugin bundle?

All version metadata resides in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) at the plugin root. This file must include `manifest_version` for the bundle version and `api_version` for SDK compatibility. Individual skills may contain additional version configurations, such as Temporal workflow constants or SDK-specific version pins in their respective configuration files.