# OpenAI Codex Plugin Manifest File Structure: Complete Schema Guide > Understand the OpenAI Codex plugin manifest file structure. Explore the complete schema guide for plugin.json, detailing name, version, skills, and interface for easy integration. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: api-reference - Published: 2026-06-14 --- **The plugin manifest is a JSON file located at `plugins//.codex-plugin/plugin.json` that defines metadata, capabilities, and UI presentation for Codex plugins using a structured schema with required fields like `name`, `version`, `skills`, and an `interface` object.** The `openai/plugins` repository establishes a standardized manifest format that powers the Codex plugin ecosystem. This JSON configuration serves as the contract between plugin developers and the marketplace, controlling everything from discovery to execution permissions while following the Codex Plugin Manifest Specification. ## Plugin Manifest Location and File Path Every Codex plugin must include a manifest file at a specific location within the repository structure. According to the source code organization, the file resides at: ``` plugins//.codex-plugin/plugin.json ``` This convention ensures consistent discovery across all plugins in the `openai/plugins` repository. For example, the Zotero plugin stores its manifest at [`plugins/zotero/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zotero/.codex-plugin/plugin.json), while the Fyxer plugin uses [`plugins/fyxer/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/fyxer/.codex-plugin/plugin.json). ## Core Plugin Manifest Schema The manifest follows the **Codex Plugin Manifest Specification**, which requires specific top-level fields to validate correctly. Missing required fields causes the plugin to be rejected during the validation process. ### Required Metadata Fields The root object must include these mandatory fields: - **name**: Unique identifier for the plugin (e.g., `"zotero"`) - **version**: Semantic version string (e.g., `"0.1.2"`) - **description**: Short text displayed in the marketplace listings - **homepage**: URL to the plugin's home page - **repository**: Source code repository URL - **license**: SPDX license identifier (e.g., `"MIT"`) - **keywords**: Array of search tags (e.g., `["zotero", "citations"]`) - **skills**: Relative path to the folder containing skill definitions (e.g., `"./skills/"`) ### Author Configuration The **author** field requires an object containing: - **name**: Developer or organization name - **email**: Optional contact address - **url**: Optional website link ### Optional App Integration Plugins may include an **apps** field that specifies a relative path to an [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file defining an MCP-compatible application. The Fyxer plugin demonstrates this pattern with `"apps": "./.app.json"`, enabling extended functionality beyond standard skills. ## The Interface Object Structure The **interface** object controls how the plugin appears to end users in the Codex marketplace and UI. ### Display and Branding Fields - **displayName**: Human-readable name shown in the UI - **shortDescription**: One-line tagline for quick identification - **longDescription**: Full description text for detailed marketplace listings - **developerName**: Company or individual author name - **category**: Marketplace classification (e.g., *Education & Research*, *Productivity*) - **brandColor**: Optional hex color code for UI theming ### Capability Definitions The **capabilities** array defines execution permissions using specific string values: - `Read`: Access to read operations - `Write`: Permission to modify data - `Interactive`: Support for interactive sessions Note that some plugins, like the read-only Fyxer implementation, may omit this array entirely. ### Legal and Asset References - **websiteURL**: Link to external plugin documentation - **privacyPolicyURL**: Required legal disclosure link - **termsOfServiceURL**: Terms of service hyperlink - **composerIcon**: Relative path to composer icon asset - **logo**: Path to logo image file - **screenshots**: Optional array of image URLs for marketplace gallery - **defaultPrompt**: Array of suggested starter prompts for users ## Plugin Manifest File Examples These implementations from the `openai/plugins` repository demonstrate the schema in practice. ### Minimal Required Configuration This example shows only the mandatory fields for a basic plugin: ```json { "name": "my-plugin", "version": "0.0.1", "description": "Brief description", "author": { "name": "My Company", "url": "https://mycompany.com" }, "homepage": "https://mycompany.com", "repository": "https://github.com/mycompany/plugins", "license": "MIT", "keywords": ["example", "plugin"], "skills": "./skills/", "interface": { "displayName": "My Plugin", "shortDescription": "One-line tagline", "longDescription": "Long description that appears in the marketplace.", "developerName": "My Company", "category": "Productivity", "capabilities": ["Read"], "websiteURL": "https://mycompany.com", "privacyPolicyURL": "https://mycompany.com/privacy", "termsOfServiceURL": "https://mycompany.com/terms", "composerIcon": "./assets/icon.png", "logo": "./assets/logo.png", "defaultPrompt": ["@MyPlugin do something"] } } ``` ### Full Implementation with App Integration This configuration from the Fyxer plugin includes the optional `apps` field linking to an MCP-compatible application descriptor: ```json { "name": "awesome-app", "version": "1.2.0", "description": "An app-style plugin", "author": { "name": "Awesome Inc.", "url": "https://awesome.inc" }, "apps": "./.app.json", "interface": { "displayName": "Awesome App", "shortDescription": "Automated workflow assistant", "longDescription": "Full marketplace description here.", "developerName": "Awesome Inc.", "category": "Productivity", "websiteURL": "https://awesome.inc", "privacyPolicyURL": "https://awesome.inc/privacy", "termsOfServiceURL": "https://awesome.inc/terms", "composerIcon": "./assets/icon.png", "logo": "./assets/logo.png", "defaultPrompt": ["@AwesomeApp analyze my data"], "brandColor": "#FF5733" } } ``` ## Validation and Schema Compliance The manifest must validate against OpenAI's **Codex Plugin Manifest Specification**. The repository enforces this schema during submission review, rejecting any plugin with missing required fields or incorrect data types. Both the Zotero and Fyxer implementations adhere to this stable contract, confirming the consistency requirements across all plugins in the ecosystem. ## Summary - The **plugin manifest** resides at `plugins//.codex-plugin/plugin.json` and serves as the canonical configuration for Codex plugins. - Required fields include **name**, **version**, **description**, **author**, **homepage**, **repository**, **license**, **keywords**, and **skills**. - The **interface** object controls marketplace presentation through **displayName**, **longDescription**, **category**, and **capabilities** arrays. - Optional **apps** fields enable MCP-compatible application integration by referencing [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) files. - Real-world examples in [`plugins/zotero/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zotero/.codex-plugin/plugin.json) and [`plugins/fyxer/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/fyxer/.codex-plugin/plugin.json) demonstrate the complete schema implementation. ## Frequently Asked Questions ### What is the required file path for a Codex plugin manifest? The manifest must be located at `plugins//.codex-plugin/plugin.json` relative to the repository root. This specific path structure enables the Codex system to discover and validate plugins automatically. ### What capabilities can a plugin declare in its manifest structure? Plugins declare permissions through the **capabilities** array within the **interface** object, supporting `Read` for data access, `Write` for modification rights, and `Interactive` for session-based interactions. Some plugins, like Fyxer, omit this field when operating in read-only mode. ### How does the apps field extend the plugin manifest structure? The optional **apps** field specifies a relative path to an [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file, enabling MCP-compatible applications that extend beyond standard skill definitions. This allows plugins to define complex application behaviors while maintaining the core manifest structure. ### What happens if required fields are missing from the plugin manifest? The Codex plugin validation process rejects manifests missing required fields such as **name**, **version**, or **interface**. The schema defined by OpenAI's Codex Plugin Manifest Specification enforces strict compliance to ensure marketplace consistency and proper plugin execution.