# Codex Plugin Manifest Contract: Required Schema and File Structure

> Understand the Codex plugin manifest contract. Discover the required schema and file structure for your plugin.json, ensuring compliance with the official OpenAI plugin repository.

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

---

**A Codex plugin manifest is a JSON file located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) that declares the plugin's identity, permissions, API specifications, and deliverables according to a strict schema enforced by the plugin-eval test suite.**

The contract governs how the OpenAI Codex platform discovers, loads, and securely executes plugins from the `openai/plugins` repository. By standardizing metadata and capability declarations in a single JSON document, the manifest ensures consistent integration behavior and security boundaries across all Codex plugins.

## File Location and Naming Convention

The manifest must reside in a hidden directory named `.codex-plugin` at the repository root, specifically at the path [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json). This convention allows Codex to recursively discover plugins by scanning for this specific file pattern across the filesystem.

## Required Schema Fields

The contract defines eight mandatory top-level fields that every manifest must include to pass validation.

### Core Identity Fields

- **id**: A unique, URL-safe string identifier (e.g., `"zoom"` or `"minimal-plugin"`).
- **name**: Human-readable display name shown in the Codex UI.
- **version**: Semantic version string following standard conventions (e.g., `"2.3.1"`).
- **description**: Concise summary of the plugin's functionality.
- **author**: Object containing at least `name` (string), optionally including `url` (string).
- **type**: Must be the literal string `"codex-plugin"` to identify the manifest format.

### Capability and Security Fields

- **permissions**: Array of permission scope strings (e.g., `"read:zoom_meetings"`, `"write:zoom_meetings"`) defining the least-privilege access the plugin requires.
- **apis**: Object describing external API dependencies. Each key maps to an endpoint configuration, typically containing an `openapi` field pointing to an OpenAPI specification URL.

## Optional Configuration Fields

Beyond the required schema, the contract supports optional fields for deliverables, branding, and metadata.

### Deliverables and Artifacts

- **primary_human_deliverable**: String path to the main output file presented to users (e.g., `"output/meeting_summary.pdf"`).
- **human_deliverables**: Array of additional file paths surfaced in the UI as supplementary outputs.
- **support_artifacts**: Array of objects describing auxiliary files (logs, data exports) with metadata such as `user_visible_default`.

### Branding and Status

- **logo** or **icons**: String paths or URLs to visual assets for marketplace display.
- **status**: Publication state string indicating maturity (`"alpha"`, `"beta"`, or `"stable"`).
- **metadata**: Free-form object for custom key-value pairs used by the plugin implementation.

## Implementation Examples from openai/plugins

### Minimal Plugin Fixture

The `minimal-plugin` fixture in the plugin-eval test suite demonstrates the minimal valid contract required to pass schema validation:

```json
{
  "id": "minimal-plugin",
  "name": "Minimal Plugin",
  "version": "0.1.0",
  "description": "A minimal but valid Codex plugin manifest for testing.",
  "author": { "name": "OpenAI" },
  "type": "codex-plugin",
  "permissions": ["read:sample_data"],
  "apis": {
    "sample": {
      "openapi": "https://example.com/openapi.json"
    }
  }
}

```

Source: [`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)

### Zoom Plugin Production Manifest

The Zoom plugin illustrates a complete production implementation including optional deliverable and branding fields:

```json
{
  "id": "zoom",
  "name": "Zoom",
  "version": "2.3.1",
  "description": "Connect Codex to Zoom meeting context, transcripts, recordings, and more.",
  "author": { "name": "Zoom", "url": "https://zoom.us" },
  "type": "codex-plugin",
  "permissions": [
    "read:zoom_meetings",
    "write:zoom_meetings",
    "read:zoom_recordings"
  ],
  "apis": {
    "rest": {
      "openapi": "https://api.zoom.us/v2/openapi.json"
    }
  },
  "primary_human_deliverable": "output/meeting_summary.pdf",
  "human_deliverables": ["output/meeting_transcript.txt"],
  "logo": "assets/logo.png"
}

```

Source: [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json)

## Schema Validation and Enforcement

The contract is enforced by the plugin-evaluator test suite defined in [`plugins/plugin-eval/tests/plugin-eval.test.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/tests/plugin-eval.test.js). This validator parses [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) to check for missing required fields, type mismatches, and invalid permission formats. The evaluator ensures that any plugin submitted to the Codex platform satisfies the manifest contract before execution is permitted.

## Summary

- The **Codex plugin manifest contract** requires a JSON file at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) containing required identity, permission, and API fields.
- **Required fields** include `id`, `name`, `version`, `description`, `author`, `type` (must be `"codex-plugin"`), `permissions`, and `apis`.
- **Optional fields** support user deliverables (`primary_human_deliverable`, `human_deliverables`), visual branding (`logo`), and lifecycle metadata (`status`).
- The schema is validated by the **plugin-eval test suite** to ensure security and consistency across the OpenAI plugins repository.

## Frequently Asked Questions

### Where must the plugin.json file be located?

Codex expects the manifest at the exact path [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) relative to the repository root. This hidden directory convention enables automatic discovery during the plugin loading process.

### What is the difference between human_deliverables and support_artifacts?

**Human deliverables** are files explicitly presented to the user as primary outputs or supplementary documents, while **support artifacts** represent technical outputs like logs or raw data files that may be hidden by default but available for debugging or advanced use cases.

### Is the apis field required if my plugin does not call external APIs?

Yes, the `apis` field is mandatory in the contract schema. If your plugin operates without external API calls, provide an empty object `{}` or define internal API schemas to satisfy the validation requirements in [`plugins/plugin-eval/tests/plugin-eval.test.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/tests/plugin-eval.test.js).

### How does Codex validate the manifest schema?

The platform uses the plugin-evaluator to parse [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json), verifying that all required fields exist, conform to expected types (strings, arrays, objects), and that the `type` field exactly matches `"codex-plugin"` according to the contract defined in the source code.