# Versioning Strategy for Codex Plugins: Semantic Versioning in OpenAI Plugins

> Learn Codex plugin versioning. Discover how semantic versioning MAJOR.MINOR.PATCH in plugin.json manages breaking changes, new features, and bug fixes for seamless OpenAI plugin development.

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

---

**TLDR:** Codex plugins use **semantic versioning** (MAJOR.MINOR.PATCH) defined in the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest file, where major versions indicate breaking changes, minor versions add backward-compatible features, and patch versions fix bugs.

The **openai/plugins** repository defines the official **versioning strategy for Codex plugins** to ensure compatibility across the ecosystem. This semantic versioning system lives in the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest and is essential for developers building and maintaining plugins for the Codex marketplace.

## Semantic Versioning in the Plugin Manifest

Every Codex plugin declares its version in the **plugin manifest** ([`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)), which serves as the authoritative source for the plugin's release version. This file sits in the `.codex-plugin` directory and uses the semantic versioning format.

In [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json), the version field follows this pattern:

```json
{
  "name": "zoom",
  "version": "1.0.2",
  "description": "Connect Codex to Zoom meeting context and build Zoom apps, bots, API integrations, SDK workflows, webhooks, and automations.",
  "apps": "./.app.json",
  "skills": "./skills/",
  "interface": {
    "displayName": "Zoom",
    "shortDescription": "Use Zoom meeting context and build Zoom integrations."
  }
}

```

The `version` field is the single source of truth that the Codex marketplace and consumers use to identify the plugin's current release.

## Understanding MAJOR.MINOR.PATCH Components

The versioning strategy for Codex plugins follows strict rules for incrementing each component of the semantic version number.

### Major Version (Breaking Changes)

Bump the **major version (X)** when introducing changes that break existing functionality. This includes removing skills, altering skill signatures, or modifying the underlying API in ways that require downstream code updates.

### Minor Version (Backward-Compatible Features)

Increment the **minor version (Y)** when adding functionality that maintains backward compatibility. New skills, optional parameters, and expanded capability sets fall into this category.

### Patch Version (Bug Fixes and Maintenance)

Update the **patch version (Z)** for bug fixes, documentation updates, or non-functional changes that do not affect the public API surface.

## Version Drift and SDK Compatibility

Plugins wrap external SDKs and APIs, creating potential compatibility challenges addressed through **versioning-and-drift** documentation. The [`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) file provides guidance on how plugin versions must stay synchronized with underlying SDK releases.

This reference documentation ensures that when a plugin updates its version number, developers verify compatibility with the external services the plugin wraps. The same pattern applies across the entire ecosystem, from [`plugins/wix/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/wix/.codex-plugin/plugin.json) to [`plugins/stripe/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/stripe/.codex-plugin/plugin.json).

## Marketplace Distribution and Update Workflows

The Codex marketplace automates version detection and distribution based on the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest.

### How the Codex Marketplace Handles Versions

When you update the version field in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) and republish the plugin bundle, the marketplace automatically makes the newer version discoverable to users. This ensures that consumers of the plugin—including Codex, Cursor, and Claude Code—receive consistent and compatible skill sets.

### Publishing a New Plugin Version

After publishing a new version, developers must follow this update workflow:

1. Bump the version in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) according to semantic versioning rules.
2. Update any SDK version pins in skill references.
3. Run the versioning-and-drift checks to ensure compatibility.
4. Republish the plugin to make it available in the marketplace.

## Summary

- **Semantic versioning** in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) is the authoritative versioning strategy for Codex plugins.
- **Major versions** signal breaking changes to skills or APIs.
- **Minor versions** indicate backward-compatible feature additions.
- **Patch versions** cover bug fixes and non-functional updates.
- The **versioning-and-drift** reference ([`versioning-and-drift.md`](https://github.com/openai/plugins/blob/main/versioning-and-drift.md)) manages SDK compatibility.
- The **Codex marketplace** automatically distributes updates when [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) versions change.

## Frequently Asked Questions

### Where is the version number defined in a Codex plugin?

The version number is defined in the `version` field of the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file located in the `.codex-plugin` directory. This manifest file serves as the authoritative source for the plugin's release version across the OpenAI plugins repository.

### When should I bump the major version of my Codex plugin?

You should bump the major version when introducing **breaking changes** such as removing skills, altering skill signatures, or changing the underlying API in ways that require consumers to update their code. Breaking changes must trigger a major version increment to signal incompatibility with previous implementations.

### How does the Codex marketplace detect new plugin versions?

The marketplace detects new versions by reading the `version` field in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) when the plugin bundle is republished. A new version becomes automatically discoverable to users once the updated manifest is submitted, ensuring tools like Codex, Cursor, and Claude Code receive the latest compatible skills.

### What is the versioning-and-drift reference?

The **versioning-and-drift** reference is a documentation file (typically [`versioning-and-drift.md`](https://github.com/openai/plugins/blob/main/versioning-and-drift.md) within skill references) that explains how a plugin's version must stay synchronized with the external SDKs or APIs it wraps. It provides compatibility guidance to prevent version mismatches between the plugin and its underlying dependencies.