# What Is the Codex Plugin Manifest? File Structure, Schema, and Validation

> Understand the Codex plugin manifest file structure, schema, and validation. Learn how to define plugin identity, capabilities, and authentication for the OpenAI Codex runtime.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: deep-dive
- Published: 2026-07-03

---

**A Codex plugin manifest is a JSON configuration file located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) that defines the plugin's identity, capabilities, authentication requirements, and permissions for the OpenAI Codex runtime.**

The **Codex plugin manifest** serves as the single source of truth for how the OpenAI platform discovers, validates, and loads third-party extensions. Every plugin bundled in the `openai/plugins` repository must include this structured JSON file to register its skills with the Codex assistant and render properly in the plugin marketplace.

## Manifest File Location and Naming Convention

The Codex runtime enforces a strict directory structure for plugin discovery. Each plugin must store its manifest at the path [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) relative to the plugin's root directory.

Real-world examples in the repository include:

- [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json) — Configuration for the Zoom integration
- [`plugins/vercel/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/vercel/.codex-plugin/plugin.json) — Configuration for the Vercel deployment plugin

When a new plugin is added to the repository, committing a correctly formatted [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) alongside the plugin's code is mandatory for automatic registration.

## Core Manifest Fields and Schema

The manifest uses a standardized JSON schema to declare the plugin's metadata and functional capabilities. The **manifestVersion** field specifies which version of the manifest format the plugin uses, ensuring backward compatibility as the platform evolves.

### Required Metadata Fields

- **name** — Human-readable plugin name (e.g., "Zoom") displayed in the marketplace
- **description** — Short summary explaining the plugin's purpose
- **version** — Semantic version string following `major.minor.patch` format
- **author** — Individual creator or organization responsible for the plugin

### Functional Configuration Fields

- **capabilities** — Array of skill names the plugin exposes to the Codex assistant
- **auth** — Authentication requirements specification (OAuth flows, API keys, etc.)
- **schema** — JSON schema describing the inputs and outputs for each declared skill
- **icons** — URLs or relative paths to plugin icon assets for UI generation
- **permissions** — Required access scopes (e.g., `read:calendar`, `write:files`)

## How the Codex Runtime Uses the Manifest

The Codex platform processes the manifest file to perform four critical operations:

1. **Validation** — Verifies plugin structure against the official schema before loading
2. **Skill Exposure** — Makes declared capabilities available to the Codex assistant for invocation
3. **Security Enforcement** — Applies authentication and permission checks when the plugin is called
4. **UI Generation** — Renders marketplace elements including icons, descriptions, and version information

According to the `openai/plugins` source code, the runtime specifically references [`plugins/codex-security/schemas/scan-manifest.schema.json`](https://github.com/openai/plugins/blob/main/plugins/codex-security/schemas/scan-manifest.schema.json) to validate manifests during the loading process.

## Reading and Validating Manifest Files

Developers can programmatically interact with Codex plugin manifests using standard file system operations and JSON schema validators.

### Loading a Manifest in Node.js

```javascript
import { readFile } from 'fs/promises';
import path from 'path';

async function loadManifest(pluginDir) {
  const manifestPath = path.join(pluginDir, '.codex-plugin', 'plugin.json');
  const raw = await readFile(manifestPath, 'utf-8');
  return JSON.parse(raw);
}

// Usage
loadManifest('plugins/zoom')
  .then(manifest => console.log('Zoom plugin version:', manifest.version))
  .catch(err => console.error('Failed to read manifest:', err));

```

### Validating Against the Official Schema

The repository includes a JSON Schema at [`plugins/codex-security/schemas/scan-manifest.schema.json`](https://github.com/openai/plugins/blob/main/plugins/codex-security/schemas/scan-manifest.schema.json) for automated validation. Use the `ajv-cli` tool to verify your manifest before submission:

```bash

# Install the JSON schema validator

npm i -g ajv-cli

# Validate a plugin's manifest

ajv validate -s plugins/codex-security/schemas/scan-manifest.schema.json \
            -d plugins/codex-security/examples/completed-scan/scan-manifest.json

```

Documentation in [`plugins/plugin-eval/README.md`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/README.md) confirms that the manifest must reside at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) for the evaluation tools to process the plugin correctly.

## Summary

- The **Codex plugin manifest** is a JSON file located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) in every plugin directory
- **Required fields** include `name`, `description`, `version`, `author`, `capabilities`, `auth`, `schema`, `icons`, `permissions`, and `manifestVersion`
- The **Codex runtime** uses the manifest to validate structure, expose skills, enforce security, and generate marketplace UI
- Developers should **validate manifests** against [`plugins/codex-security/schemas/scan-manifest.schema.json`](https://github.com/openai/plugins/blob/main/plugins/codex-security/schemas/scan-manifest.schema.json) before committing to the repository

## Frequently Asked Questions

### Where is the Codex plugin manifest file located?

The manifest file must be placed at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) relative to the plugin's root directory. For example, the Vercel plugin stores its manifest at [`plugins/vercel/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/vercel/.codex-plugin/plugin.json) within the repository structure.

### What fields are required in a Codex plugin manifest?

At minimum, the manifest must include `name`, `description`, `version`, `author`, `capabilities`, `auth`, `schema`, `icons`, `permissions`, and `manifestVersion`. These fields define the plugin's identity, security requirements, and functional capabilities for the Codex runtime.

### How do I validate my Codex plugin manifest?

Use the JSON Schema validator `ajv-cli` against the official schema located at [`plugins/codex-security/schemas/scan-manifest.schema.json`](https://github.com/openai/plugins/blob/main/plugins/codex-security/schemas/scan-manifest.schema.json). Run: `ajv validate -s [schema-path] -d [manifest-path]` to check your file before submission.

### What happens if the manifest file is missing or malformed?

The Codex runtime will fail to load the plugin during the validation phase. The platform requires a correctly formatted manifest at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to register the plugin, expose its skills to the assistant, and enforce authentication checks.