# OpenAI Plugin Manifest Schema: Complete JSON Reference and File Structure

> Discover the OpenAI plugin manifest schema. Learn the required fields and file structure to enable ChatGPT to interact with external APIs effectively. Get the complete JSON reference here.

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

---

**The OpenAI plugin manifest schema is a JSON-based specification that requires seven top-level fields—`schema_version`, `name_for_human`, `name_for_model`, `description_for_human`, `description_for_model`, `auth`, and `api`—plus optional branding and legal metadata to enable ChatGPT to discover and interact with external APIs.**

The **OpenAI plugin manifest schema** defines the structured metadata required to register a plugin with the ChatGPT platform. According to the `openai/plugins` repository, every plugin must expose a [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file that follows this strict schema, allowing the model to understand authentication flows, API endpoints, and display information. This specification ensures consistent integration across the plugin ecosystem.

## Required Fields in the OpenAI Plugin Manifest Schema

Every manifest must include seven mandatory top-level fields that describe the plugin's identity, capabilities, and API contract.

### Schema Version and Naming

The **`schema_version`** field declares the manifest specification version. Currently, the only supported value is `"v1"`.

The **`name_for_human`** field provides the human-readable display name (e.g., "Wix Headless"), while **`name_for_model`** serves as the machine identifier. The model-facing name must be a short, lowercase, alphanumeric string without spaces (e.g., `"wix_headless"`).

### Human and Model Descriptions

The **`description_for_human`** field contains a comprehensive explanation of the plugin's functionality for end users. The **`description_for_model`** field provides a concise summary (maximum 500 characters) that the LLM uses to determine when to invoke the plugin during conversations.

### Authentication Configuration

The **`auth`** object defines how ChatGPT authenticates with your API. The **`type`** field accepts three values: `"none"`, `"service_http"`, or `"oauth"`.

For **OAuth** configurations, you must include:
- **`authorization_url`**: The OAuth authorization endpoint
- **`client_url`**: The token exchange endpoint
- **`scope`** (optional): Space-separated permissions
- **`instructions`** (optional): Human-readable setup guidance

For **`service_http`**, no additional fields are required. The **`none`** type indicates the plugin requires no authentication.

### API Specification

The **`api`** object describes the underlying API surface. It requires:
- **`type`**: Must be `"openapi"` (future types may be supported)
- **`url`**: HTTPS URL to the OpenAPI 3.x specification file
- **`is_user_authenticated`**: Boolean indicating whether the user's session token should be forwarded to your API

## Optional Fields for Branding and Legal Compliance

The schema supports three optional fields for production deployment:

- **`logo_url`**: HTTPS URL to a 1:1 aspect ratio PNG or SVG image (maximum 1 MB)
- **`contact_email`**: Developer contact address for support inquiries
- **`legal_info_url`**: Link to terms of service or legal documentation

## Complete OpenAI Plugin Manifest Example

The following example demonstrates a fully configured manifest implementing OAuth authentication:

```json
{
  "schema_version": "v1",
  "name_for_human": "Wix Headless",
  "name_for_model": "wix_headless",
  "description_for_human": "Create, update, and publish Wix site content programmatically.",
  "description_for_model": "Manipulates Wix site pages, collections, and assets.",
  "auth": {
    "type": "oauth",
    "authorization_url": "https://www.wix.com/oauth/authorize",
    "client_url": "https://www.wix.com/oauth/token",
    "scope": "site_content",
    "instructions": "Log in to Wix to obtain an access token."
  },
  "api": {
    "type": "openapi",
    "url": "https://plugins.wix.com/openapi.yaml",
    "is_user_authenticated": true
  },
  "logo_url": "https://plugins.wix.com/logo.png",
  "contact_email": "support@wix.com",
  "legal_info_url": "https://www.wix.com/terms"
}

```

## Repository Structure and Implementation

In the `openai/plugins` repository, each plugin stores its manifest in a standardized location. The **plugin-eval** plugin stores its manifest at [`plugins/plugin-eval/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/.codex-plugin/plugin.json), demonstrating the required field structure.

Documentation in [`plugins/zoom/README.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/README.md) and [`plugins/vercel/README.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/README.md) confirms that each plugin bundle includes a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file. This consistent path structure allows the OpenAI platform to automatically discover and validate plugin configurations across the repository.

## Summary

- The **OpenAI plugin manifest schema** requires seven mandatory fields: `schema_version`, `name_for_human`, `name_for_model`, `description_for_human`, `description_for_model`, `auth`, and `api`.
- Authentication supports three modes: **none**, **service_http**, and **oauth**, with OAuth requiring specific endpoint URLs.
- The **API object** must reference an OpenAPI 3.x specification via HTTPS and declare whether user authentication is required.
- Optional fields include `logo_url`, `contact_email`, and `legal_info_url` for production deployment.
- Repository implementations store manifests in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) within each plugin directory, as seen in [`plugins/plugin-eval/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/.codex-plugin/plugin.json).

## Frequently Asked Questions

### What is the current schema_version for OpenAI plugins?

The only supported value is `"v1"`. This field is mandatory and must be declared as a string in the root of the manifest object. Future versions of the OpenAI plugin manifest schema may introduce new version identifiers, but all current implementations must use `"v1"`.

### How do I define OAuth authentication in the manifest?

Set the `auth.type` field to `"oauth"` and include both `authorization_url` and `client_url` fields. The `authorization_url` specifies where users are redirected to authorize the plugin, while `client_url` handles the token exchange. You may optionally specify `scope` for permission scopes and `instructions` for user guidance.

### Where should the plugin.json file be located in the repository?

According to the repository structure in `openai/plugins`, each plugin must store its manifest at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) within the plugin's root directory. This convention is documented in [`plugins/zoom/README.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/README.md) and [`plugins/vercel/README.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/README.md), and implemented in [`plugins/plugin-eval/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/.codex-plugin/plugin.json).

### What is the difference between name_for_human and name_for_model?

The `name_for_human` field displays the plugin name in the ChatGPT UI and can contain spaces and mixed case (e.g., "Wix Headless"). The `name_for_model` field is the internal identifier used by the LLM to reference the plugin, must be lowercase, and must use only alphanumeric characters and underscores (e.g., `"wix_headless"`).