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

> Understand the essential structure for your plugin.json manifest file. Learn about required fields like name, version, description, author, and interface for OpenAI plugins.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: api-reference
- Published: 2026-06-29

---

**A [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file must be a valid JSON object located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugin.json).

- **Full path**: [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/hooks.json) file.
- **`mcpServers`**: Path to a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file for MCP server configuration.
- **`apps`**: Path to a [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/fixtures/minimal-plugin/.codex-plugin/plugin.json) demonstrates the smallest valid configuration:

```json
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "A minimal but valid plugin manifest.",
  "author": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "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:

```json
{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "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`](https://github.com/openai/plugins/blob/main/plugin.json) must reside at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js) which enforces the schema from [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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.