# OpenAI Plugin Manifest Structure: Complete Guide to plugin.json

> Understand the OpenAI plugin manifest structure with this complete guide to plugin.json. Learn how to define your plugin's identity, capabilities, and UI rendering.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: deep-dive
- Published: 2026-09-12

---

**The [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest serves as the canonical configuration file that defines every OpenAI plugin's identity, capabilities, and entry points through a standardized schema containing required metadata fields, file path references, and an `interface` object for UI rendering.**

The `openai/plugins` repository hosts the source code for official Codex and ChatGPT plugins, with each integration defined by a mandatory [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file. Understanding the plugin manifest structure is essential for developers building custom integrations, as this single file dictates how the platform discovers, displays, and executes plugin functionality.

## Core Schema of the Plugin Manifest

The root of every [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) follows a strict schema enforced by the Codex runtime. Twelve primary fields govern plugin identification and behavior, with additional optional extensions for API definitions.

### Identity and Metadata Fields

Every manifest must declare fundamental identity properties that the platform uses for registration and discovery.

- **`name`**: The URL-safe identifier used in routing (e.g., `"google-drive"`)
- **`version`**: Semantic versioning string (e.g., `"0.1.15"`)
- **`description`**: One-line summary displayed in plugin listings
- **`author`**: Object containing `name`, `email`, and `url` properties
- **`homepage`**: Human-readable landing page URL
- **`repository`**: Source code location, typically `"https://github.com/openai/plugins"`
- **`license`**: SPDX license identifier (e.g., `"MIT"`)
- **`keywords`**: Array of discovery tags (e.g., `["google-drive", "productivity"]`)

### File Path References

The manifest points to executable code through relative paths that the runtime resolves against the plugin root.

- **`skills`**: Relative path to the folder containing skill definitions (e.g., `"./skills/"`)
- **`apps`**: Relative path to the MCP app definition file (e.g., `"./.app.json"`)

### Interface Configuration

The **`interface`** object contains UI-specific metadata and capability declarations consumed by the Codex runtime. Required properties include:

- **`displayName`**: Human-readable name shown in the UI
- **`shortDescription`**: Brief marketing tagline
- **`longDescription`**: Full description supporting line breaks
- **`developerName`**: Company or individual author name
- **`category`**: Functional grouping (e.g., `Productivity`, `Creativity`)
- **`capabilities`**: Array of allowed interaction modes (`Interactive`, `Write`, etc.)
- **`composerIcon`** and **`logo`**: Asset paths for visual identification
- **`websiteURL`**, **`privacyPolicyURL`**, **`termsOfServiceURL`**: Legal and support links
- **`defaultPrompt`**: Array of sample prompts surfaced by the UI

Optional interface properties include **`brandColor`** (hex color for UI theming) and **`screenshots`** (array of image paths).

### Optional API Configuration

The **`api`** object is optional and describes REST or GraphQL endpoints provided by the plugin. When present, it typically contains a `baseUrl` field defining the root endpoint for all plugin operations.

## Complete plugin.json Example

Here is a minimal yet complete manifest based on the schema implemented in [`plugins/canva/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/canva/.codex-plugin/plugin.json) and [`plugins/google-drive/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/google-drive/.codex-plugin/plugin.json):

```json
{
  "name": "example-plugin",
  "version": "1.0.0",
  "description": "One-sentence summary of the plugin.",
  "author": {
    "name": "Acme Corp.",
    "email": "dev@acme.com",
    "url": "https://acme.com"
  },
  "homepage": "https://acme.com/example",
  "repository": "https://github.com/acme/example-plugin",
  "license": "MIT",
  "keywords": ["example", "demo"],
  "skills": "./skills/",
  "apps": "./.app.json",
  "interface": {
    "displayName": "Example Plugin",
    "shortDescription": "Brief tagline",
    "longDescription": "Full description with usage details.",
    "developerName": "Acme Corp.",
    "category": "Productivity",
    "capabilities": ["Interactive", "Write"],
    "composerIcon": "./assets/composer-icon.png",
    "logo": "./assets/logo.png",
    "websiteURL": "https://acme.com",
    "privacyPolicyURL": "https://acme.com/privacy",
    "termsOfServiceURL": "https://acme.com/terms",
    "defaultPrompt": ["Show me a summary of today's activity"],
    "brandColor": "#123456",
    "screenshots": ["./screens/01.png"]
  }
}

```

## Plugin Manifest Locations in the Repository

In the `openai/plugins` codebase, each plugin maintains its manifest within a `.codex-plugin` directory. These canonical examples demonstrate the complete structure:

- **Canva**: [`plugins/canva/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/canva/.codex-plugin/plugin.json) (references [`plugins/canva/.app.json`](https://github.com/openai/plugins/blob/main/plugins/canva/.app.json) and assets)
- **Google Drive**: [`plugins/google-drive/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/google-drive/.codex-plugin/plugin.json) (references [`plugins/google-drive/.app.json`](https://github.com/openai/plugins/blob/main/plugins/google-drive/.app.json) and `plugins/google-drive/skills/`)
- **Slack**: [`plugins/slack/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/slack/.codex-plugin/plugin.json) with skills in `plugins/slack/skills/`
- **Stripe**: [`plugins/stripe/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/stripe/.codex-plugin/plugin.json) with skills in `plugins/stripe/skills/`

## Summary

- The [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file serves as the single source of truth for OpenAI plugin configuration in the `openai/plugins` repository.
- Required fields include `name`, `version`, `description`, `author`, `skills`, `apps`, and the `interface` object.
- The `interface` object controls UI rendering through `displayName`, `capabilities`, and brand asset paths.
- Optional sections like `api` and `brandColor` extend functionality without breaking core compatibility.
- Manifests reside in `.codex-plugin` directories alongside skill definitions and MCP app configurations.

## Frequently Asked Questions

### What is the required schema for a plugin.json file?

Every manifest must include the `name`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords`, `skills`, `apps`, and `interface` fields. The `interface` object itself requires `displayName`, `shortDescription`, `longDescription`, `developerName`, `category`, `capabilities`, `composerIcon`, `logo`, and URL fields for privacy policies and terms of service.

### Where does the plugin.json file reside in the openai/plugins repository?

Each plugin stores its manifest in a `.codex-plugin` subdirectory within its plugin folder. For example, the Google Drive manifest lives at [`plugins/google-drive/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/google-drive/.codex-plugin/plugin.json), while the Canva manifest resides at [`plugins/canva/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/canva/.codex-plugin/plugin.json).

### What capabilities can be defined in the interface object?

The `capabilities` array within the `interface` object accepts strings defining interaction modes. Common values found in the repository include `Interactive` for real-time user engagement and `Write` for content generation permissions. These values determine how the Codex runtime executes plugin functions.

### Is the API section required in every plugin manifest?

No, the `api` object is optional. Only plugins exposing REST or GraphQL endpoints include this section, typically specifying a `baseUrl`. Stateless plugins relying solely on the MCP protocol through the `apps` and `skills` references omit this field entirely.