OpenAI Plugin Manifest Schema: Complete JSON Reference and File Structure

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 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:

{
  "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": "[email protected]",
  "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, demonstrating the required field structure.

Documentation in plugins/zoom/README.md and plugins/vercel/README.md confirms that each plugin bundle includes a .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 within each plugin directory, as seen in 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 within the plugin's root directory. This convention is documented in plugins/zoom/README.md and plugins/vercel/README.md, and implemented in 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").

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}