# .codex-plugin/plugin.json Schema: Complete Reference for OpenAI Codex Plugins

> Explore the complete .codex-plugin/plugin.json schema reference for OpenAI Codex Plugins. Understand metadata, UI config, and asset paths with this essential guide.

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

---

**The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file is a JSON manifest that defines a Codex plugin's metadata, UI configuration, and asset paths, using a strict schema with required fields like `name`, `version`, `skills`, and a nested `interface` object.**

The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) schema serves as the single source of truth for the Codex runtime in the **openai/plugins** repository. This manifest tells the system how to load skill definitions, render UI components in the composer, and display the plugin in the marketplace.

## Top-Level Schema Fields

Every plugin manifest must reside at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) relative to the plugin root. The schema consists of string fields, objects, and arrays that configure both runtime behavior and presentation.

### Identification and Metadata

These fields define the plugin's identity and discoverability:

- **name** (`string`, required): Machine-readable identifier (e.g., `"hex"`, `"factset"`).
- **version** (`string`, required): Semantic version following standard versioning (e.g., `"0.1.0"`).
- **description** (`string`, required): Brief human-readable summary of functionality.
- **author** (`object`, required): Contains `name` (`string`, required) and optional `url` (`string`) pointing to the author's website.
- **homepage** (`string`, required): URL to the plugin's public landing page.
- **repository** (`string`, required): URL to the source repository (typically the openai/plugins repo).
- **license** (`string`, required): SPDX license identifier (e.g., `"MIT"`, `"Proprietary"`).
- **keywords** (`array<string>`, optional): Tags for search and categorization (e.g., `["analytics", "data"]`).

### Asset Paths

These fields point to the plugin's executable components:

- **skills** (`string`, required): Relative path to the directory containing skill definitions (e.g., `"./skills/"`).
- **apps** (`string`, required): Relative path to the [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file that defines UI components (e.g., `"./.app.json"`).

## Interface Object Schema

The `interface` object (required) contains all UI-related metadata that the Codex runtime uses to render the plugin in the composer and marketplace.

### Display Properties

- **displayName** (`string`, required): Human-readable name shown in the UI.
- **shortDescription** (`string`, required): One-line description for plugin listings.
- **longDescription** (`string`, required): Full description displayed on detail pages.
- **developerName** (`string`, required): Name of the organization that built the plugin.
- **category** (`string`, required): High-level classification (e.g., `"Data & Analytics"`, `"Productivity"`).
- **brandColor** (`string`, required): Hex color code for UI accents (e.g., `"#182A4D"`).

### Interaction Configuration

- **capabilities** (`array<string>`, required): Supported interaction modes. Common values include `"Read"`, `"Write"`, and `"Interactive"`. May be empty.
- **defaultPrompt** (`string` or `array<string>`, required): Default prompt(s) suggested to users to invoke the plugin. As demonstrated in [`plugins/factset/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/factset/.codex-plugin/plugin.json), this can be an array of multiple example prompts.

### Visual Assets

- **composerIcon** (`string`, required): Relative path to the 32px icon displayed in the composer.
- **logo** (`string`, required): Relative path to the plugin logo used in the marketplace.
- **screenshots** (`array<string>`, optional): Array of paths to screenshot images for marketplace display.

### Legal and Support Links

- **websiteURL** (`string`, required): Link to the plugin's public website.
- **privacyPolicyURL** (`string`, optional): Link to the privacy policy.
- **termsOfServiceURL** (`string`, optional): Link to the terms of service.

## Required vs Optional Fields

Understanding the strict requirements prevents validation errors during plugin loading.

**Required fields** (must appear for valid plugin loading):
- `name`, `version`, `description`, `author.name`
- `homepage`, `repository`, `license`
- `skills`, `apps`
- `interface` (and all its sub-fields except `privacyPolicyURL`, `termsOfServiceURL`, and `screenshots`)

**Optional fields** (may be omitted, falling back to defaults):
- `author.url`, `keywords`
- `interface.privacyPolicyURL`, `interface.termsOfServiceURL`, `interface.screenshots`

## Complete Example Manifest

Below is a minimal yet valid [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) that satisfies all schema requirements:

```json
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Brief description of what the plugin does.",
  "author": { "name": "My Company" },
  "homepage": "https://mycompany.com",
  "repository": "https://github.com/openai/plugins/tree/main/plugins/my-plugin",
  "license": "MIT",
  "keywords": [],
  "skills": "./skills/",
  "apps": "./.app.json",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "One-line summary.",
    "longDescription": "Longer description used in the marketplace.",
    "developerName": "My Company",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
    "brandColor": "#123456",
    "defaultPrompt": "Ask me to do something with My Plugin.",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "websiteURL": "https://mycompany.com",
    "privacyPolicyURL": "https://mycompany.com/privacy",
    "termsOfServiceURL": "https://mycompany.com/terms",
    "screenshots": []
  }
}

```

Replace placeholder paths with actual files relative to your plugin directory.

## Reference Implementations

The openai/plugins repository contains concrete implementations that demonstrate the full schema:

- **Hex**: [`plugins/hex/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/hex/.codex-plugin/plugin.json) demonstrates optional UI links and complete interface configuration.
- **FactSet**: [`plugins/factset/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/factset/.codex-plugin/plugin.json) shows the `defaultPrompt` field as an array and empty capabilities.
- **Docket**: [`plugins/docket/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/docket/.codex-plugin/plugin.json) provides another example of the full schema structure.
- **Help-Scout**: [`plugins/help-scout/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/help-scout/.codex-plugin/plugin.json) illustrates standard field usage.

## Summary

- The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file is the mandatory manifest that configures every Codex plugin in the openai/plugins repository.
- **Required fields** include `name`, `version`, `skills`, `apps`, and the complete `interface` object (minus optional URL fields).
- **Optional fields** like `keywords`, `screenshots`, and legal URLs enhance discoverability and compliance but are not mandatory for loading.
- The `interface` object controls all UI rendering, including icons, colors, prompts, and capabilities.
- Real-world examples in [`plugins/hex/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/hex/.codex-plugin/plugin.json) and [`plugins/factset/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/factset/.codex-plugin/plugin.json) serve as authoritative references.

## Frequently Asked Questions

### What is the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file used for?

The file serves as the manifest that tells the Codex runtime how to load and display a plugin. It defines the plugin's identity, points to skill definitions and UI components, and configures how the plugin appears in the composer and marketplace.

### Is the `author.url` field required?

No, only `author.name` is required within the `author` object. The `author.url` field is optional and can be omitted if the author does not have a specific website to reference.

### Can `defaultPrompt` be an array instead of a string?

Yes, according to the schema implementation in [`plugins/factset/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/factset/.codex-plugin/plugin.json), the `defaultPrompt` field accepts either a single string or an array of strings to provide multiple example prompts for users.

### Where should the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file be located?

The file must reside at the path [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) relative to the plugin root directory. This specific location is hardcoded in the Codex runtime as the entry point for plugin discovery and loading.