Required Structure for a plugin.json Manifest File in OpenAI Plugins

A plugin.json file must be a valid JSON object located at .codex-plugin/plugin.json containing five required fields—name, version, description, author (with name), and interface (with displayName)—along with optional path configurations and UI metadata.

The plugin.json manifest serves as the canonical descriptor for Codex plugins in the openai/plugins repository. It enables the discovery system to identify plugin capabilities, locate assets, and render marketplace listings. According to the specification defined in .agents/skills/plugin-creator/references/plugin-json-spec.md, the manifest follows a strict schema divided into three functional groups: top-level metadata, path configuration, and interface definitions.

Required Location and File Path

The Codex discovery system specifically searches for a hidden .codex-plugin/ directory at the repository root. Inside this directory, the manifest must be named exactly plugin.json.

• Full path: .codex-plugin/plugin.json
• Discovery mechanism: The system traverses the repository looking for this hidden folder and validates the manifest using the logic in plugins/plugin-eval/src/evaluators/plugin.js

Top-Level Metadata Fields

These fields identify the plugin and provide basic discovery data. Five fields are strictly required for validation.

Required Fields

• name: A kebab-case identifier (no spaces) that must match the folder name. Used as the canonical plugin ID.
• version: Semantic version string (e.g., 1.2.0).
• description: One-sentence summary of functionality.
• author: Object containing at least name. The fields email and url are recommended but optional.
• interface: Object containing UI metadata (detailed below).

Optional Fields

• homepage: URL to documentation or landing page.
• repository: URL of the source code repository.
• license: SPDX-style identifier (e.g., MIT).
• keywords: Array of strings for search and categorization.

Path Configuration Fields

These fields specify relative paths to plugin assets. All paths must start with ./ and be relative to the plugin root.

• skills: Path to skill definitions directory (typically ./skills/).
• hooks: Path to a hooks.json file.
• mcpServers: Path to a .mcp.json file for MCP server configuration.
• apps: Path to a .app.json file for additional app integrations.

Specifying these paths augments the default discovery mechanism rather than replacing it.

The Interface Object

The interface object contains all UI/UX metadata shown in the ChatGPT plugin marketplace. It requires at least one field.

Required Interface Field

• displayName: Human-readable title displayed in marketplace listings.

Optional Interface Fields

• shortDescription: Subtitle for compact views.
• longDescription: Full description for the details page.
• developerName: Publishing organization (e.g., OpenAI).
• category: High-level category (e.g., Productivity).
• capabilities: Array of capability strings (Interactive, Write, etc.).
• websiteURL: Link to the public website.
• privacyPolicyURL: Link to privacy policy.
• termsOfServiceURL: Link to terms of service.
• defaultPrompt: Array of up to three starter prompts (each ≤ 128 characters).
• brandColor: Hex color code (e.g., #3B82F6).
• composerIcon: Path to composer UI icon.
• logo: Path to larger logo asset.
• screenshots: Array of PNG filenames (must reside under ./assets/).

Validation and Schema Enforcement

The validation logic in plugins/plugin-eval/src/evaluators/plugin.js enforces the required structure when evaluating plugins. This evaluator checks for the presence of mandatory fields (name, version, description, author.name, interface.displayName) and validates that the JSON conforms to the schema defined in the specification document.

Complete plugin.json Examples

Minimal Valid Manifest

This example from plugins/plugin-eval/fixtures/minimal-plugin/.codex-plugin/plugin.json demonstrates the smallest valid configuration:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "A minimal but valid plugin manifest.",
  "author": {
    "name": "Jane Doe",
    "email": "[email protected]",
    "url": "https://github.com/janedoe"
  },
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "Demo plugin",
    "longDescription": "This plugin demonstrates the required manifest fields."
  }
}

Full-Featured Manifest

This comprehensive example from the official spec shows all available fields:

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "[email protected]",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": "./skills/",
  "hooks": "./hooks.json",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json",
  "interface": {
    "displayName": "Plugin Display Name",
    "shortDescription": "Short description for subtitle",
    "longDescription": "Long description for details page",
    "developerName": "OpenAI",
    "category": "Productivity",
    "capabilities": ["Interactive", "Write"],
    "websiteURL": "https://openai.com/",
    "privacyPolicyURL": "https://openai.com/policies/row-privacy-policy/",
    "termsOfServiceURL": "https://openai.com/policies/row-terms-of-use/",
    "defaultPrompt": [
      "Summarize my inbox and draft replies for me.",
      "Find open bugs and turn them into Linear tickets.",
      "Review today's meetings and flag scheduling gaps."
    ],
    "brandColor": "#3B82F6",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "screenshots": [
      "./assets/screenshot1.png",
      "./assets/screenshot2.png",
      "./assets/screenshot3.png"
    ]
  }
}

Summary

• plugin.json must reside at .codex-plugin/plugin.json relative to the plugin root.
• Five fields are mandatory: name, version, description, author.name, and interface.displayName.
• Path fields (skills, hooks, mcpServers, apps) must use relative paths starting with ./.
• The interface object controls marketplace presentation and supports branding assets, URLs, and starter prompts.
• Validation occurs through plugins/plugin-eval/src/evaluators/plugin.js which enforces the schema from .agents/skills/plugin-creator/references/plugin-json-spec.md.

Frequently Asked Questions

Where must the plugin.json file be located?

The file must be placed at .codex-plugin/plugin.json inside the plugin's root directory. The Codex discovery system specifically looks for this hidden folder to identify plugin packages.

Which fields are absolutely required in a plugin.json manifest?

You must include name (kebab-case), version (semantic versioning), description (one sentence), author (with at least a name sub-field), and interface (with at least a displayName sub-field). All other fields are optional according to the openai/plugins specification.

Can I use custom paths for plugin assets?

Yes. While the discovery mechanism has defaults, you can specify custom relative paths using the skills, hooks, mcpServers, and apps fields. All paths must start with ./ and be relative to the plugin root.

How does the system validate the plugin.json structure?

The validation logic in plugins/plugin-eval/src/evaluators/plugin.js checks for required fields and schema compliance when a plugin is evaluated. This ensures that only properly formatted manifests with complete metadata are recognized by the Codex plugin marketplace.

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