OpenAI Plugin Manifest Structure: Complete Guide to plugin.json

The 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 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 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 and plugins/google-drive/.codex-plugin/plugin.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 (references plugins/canva/.app.json and assets)
• Google Drive: plugins/google-drive/.codex-plugin/plugin.json (references plugins/google-drive/.app.json and plugins/google-drive/skills/)
• Slack: plugins/slack/.codex-plugin/plugin.json with skills in plugins/slack/skills/
• Stripe: plugins/stripe/.codex-plugin/plugin.json with skills in plugins/stripe/skills/

Summary

• The 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, while the Canva manifest resides at 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}