# How to Structure plugin.json with All Required Fields for OpenAI Plugins

> Master your OpenAI plugin development by structuring your plugin.json accurately. Learn the required fields and nested interface specifications for seamless integration and validation.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-28

---

**The OpenAI Codex plugin system requires a manifest file at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) containing 12 top-level fields and a nested `interface` object with 14 additional fields, all strictly enforced by the validator at [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js).**

Every plugin in the `openai/plugins` repository must include a complete [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest to be discovered and loaded by the Codex system. This JSON file defines your plugin's identity, versioning, UI presentation, and resource paths according to the strict validation rules specified in the reference documentation.

## Required Top-Level Fields

The manifest must include these fields at the root level, as 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):

- **`name`** – A kebab-case identifier that must match the plugin folder name exactly; serves as the component namespace.
- **`version`** – Semantic version string (e.g., `"1.2.0"`) used for upgrade checks.
- **`description`** – One-sentence summary displayed in marketplace listings.
- **`author`** – Object containing `name`, `email`, and `url` for the publisher.
- **`homepage`** – URL for documentation or help pages.
- **`repository`** – Link to the source code repository.
- **`license`** – SPDX-compatible license string (e.g., `"MIT"`).
- **`keywords`** – Array of searchable tags (e.g., `["automation", "productivity"]`).
- **`skills`** – Relative path to the folder containing skill implementations.
- **`hooks`** – Path to a [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) file (provide even if empty).
- **`mcpServers`** – Path to the MCP configuration file ([`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)).
- **`apps`** – Path to the optional app manifest ([`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)).

### Path Conventions

All path values—including `skills`, `hooks`, `mcpServers`, `apps`, and asset references—must start with `./` and be relative to the plugin root directory.

## Required Interface Object Fields

The `interface` object supplies UI metadata for the ChatGPT plugin marketplace and composer. Omitting these fields causes the plugin to render incorrectly in the UI.

- **`displayName`** – Human-readable title shown on the plugin card.
- **`shortDescription`** – Subtitle displayed in compact views.
- **`longDescription`** – Full description for the detail page.
- **`developerName`** – Publishing organization name (e.g., `"OpenAI"`).
- **`category`** – Broad grouping (e.g., `"Productivity"`).
- **`capabilities`** – Array of features (e.g., `["Interactive", "Write"]`).
- **`websiteURL`** – Public website for the plugin.
- **`privacyPolicyURL`** – URL to the privacy policy.
- **`termsOfServiceURL`** – URL to the terms of service.
- **`defaultPrompt`** – Array of up to three starter prompts for the Composer UI.
- **`brandColor`** – Hex color code for the plugin card background.
- **`composerIcon`** – Path to the icon shown in the Composer.
- **`logo`** – Path to the logo displayed on the plugin card.
- **`screenshots`** – Array of PNG file paths (under `./assets/`) for marketplace previews.

## Validation and Error Handling

The built-in validator at [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js) enforces every required field at load time. If any field is missing, the plugin is rejected with a specific error message such as:

```

plugin.json is missing the required `name` field.

```

Missing the `interface` object entirely allows the plugin to load but prevents proper rendering in the ChatGPT marketplace UI.

## Complete plugin.json Example

Below is a minimal, fully-populated manifest that satisfies all validator requirements. Replace placeholder values with your plugin-specific information.

```json
{
  "name": "my-awesome-plugin",
  "version": "1.0.0",
  "description": "A short description of what the plugin does",
  "author": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "url": "https://github.com/janedoe"
  },
  "homepage": "https://github.com/janedoe/my-awesome-plugin#readme",
  "repository": "https://github.com/janedoe/my-awesome-plugin",
  "license": "MIT",
  "keywords": ["automation", "productivity"],
  "skills": "./skills/",
  "hooks": "./hooks.json",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json",
  "interface": {
    "displayName": "My Awesome Plugin",
    "shortDescription": "Quickly do awesome things",
    "longDescription": "Detailed description of the plugin’s capabilities, usage, and benefits.",
    "developerName": "OpenAI",
    "category": "Productivity",
    "capabilities": ["Interactive", "Write"],
    "websiteURL": "https://myawesomeplugin.com",
    "privacyPolicyURL": "https://myawesomeplugin.com/privacy",
    "termsOfServiceURL": "https://myawesomeplugin.com/terms",
    "defaultPrompt": [
      "Summarize my inbox",
      "Create a new task in Linear",
      "Generate a meeting agenda"
    ],
    "brandColor": "#3B82F6",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "screenshots": [
      "./assets/screenshot1.png",
      "./assets/screenshot2.png",
      "./assets/screenshot3.png"
    ]
  }
}

```

## Directory Structure and Naming Consistency

Maintain consistency between your folder structure and manifest values to ensure proper discovery:

- **Manifest location** – Must be at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) exactly.
- **Naming consistency** – The folder name, the `name` field value, and the entry in [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) must all match exactly using kebab-case with no spaces.
- **Asset organization** – Store icons and screenshots in `./assets/` and reference them with relative paths starting with `./`.

A typical plugin layout looks like this:

```

my-awesome-plugin/
├── .codex-plugin/
│   └── plugin.json          ← manifest
├── skills/
│   └── ...                  ← skill implementations
├── hooks.json               ← hook configuration
├── .mcp.json                ← MCP server config
├── .app.json                ← app manifest
└── assets/
    ├── icon.png
    ├── logo.png
    └── screenshot1.png

```

## Summary

- The [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest requires 12 top-level fields and an `interface` object containing 14 UI-specific fields.
- All paths must be relative starting with `./` and point to existing files.
- The validator at [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js) rejects manifests missing any required field.
- The folder name must match the `name` field exactly in kebab-case format.
- Reference documentation is located at [`.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

### What happens if I omit a required field in plugin.json?

The validator in [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js) will reject the plugin at load time, displaying a specific error message indicating which required field is missing. The plugin will not be available in the marketplace until all required fields are present.

### Can I use absolute paths for the skills or assets fields?

No. According to the path conventions in the `openai/plugins` repository, all path values—including `skills`, `hooks`, `mcpServers`, `apps`, and asset references—must use relative paths starting with `./` and be relative to the plugin root directory.

### How does the name field in plugin.json relate to the folder structure?

The `name` field must match the plugin folder name exactly using kebab-case (e.g., `my-awesome-plugin`). This consistency is required for the component namespace resolution and marketplace entry alignment. The validator checks this correspondence when loading the plugin.

### Where can I find the official specification for all plugin.json fields?

The authoritative specification is located at [`.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) in the `openai/plugins` repository. This document defines every field, including type requirements, path conventions, and validation rules enforced by the plugin evaluator.