Requirements for the OpenAPI Schema File in an OpenAI Plugin: A Complete Technical Checklist

An OpenAI plugin must expose a valid OpenAPI 3.x specification via HTTPS with CORS enabled, containing mandatory fields including info, servers, and paths, with all references resolvable and security schemes properly declared.

The openai/plugins repository defines the strict technical contract that governs how the OpenAI platform discovers, validates, and executes plugin APIs. Understanding the specific requirements for the OpenAPI schema file is essential for marketplace approval and ensures the language model can generate reliable function calls against your endpoints.

OpenAPI Version and Format Requirements

Your schema must declare OpenAPI 3.0.x or newer at the document root. The platform explicitly rejects Swagger 2.0 specifications. According to plugins/zoom/skills/rest-api/references/openapi.md, the repository demonstrates upgrading legacy OpenAPI v2 definitions to the required 3.x format before plugin integration.

The document must be served with the correct MIME type: application/json for .json files or application/yaml/text/yaml for .yaml specifications. This ensures the platform parser correctly interprets the payload during the validation phase.

Hosting and Accessibility Requirements

The schema URL defined in your plugin manifest must satisfy several network-layer constraints:

• HTTPS only: The endpoint must use a valid TLS certificate. As shown in plugins/vercel/skills/vercel-firewall/SKILL.md, schema references must point to https:// URLs. Self-signed certificates are explicitly rejected and will cause immediate validation failure.

• CORS-enabled: The server must allow cross-origin GET requests from any origin without requiring authentication. The platform fetches the schema from sandboxed browser environments; any CORS blockage or authentication gate causes validation to fail. The Zoom plugin example in plugins/zoom/skills/rest-api/references/openapi.md demonstrates this by hosting the spec on a raw GitHub URL with permissive headers.

• Stable URL: The location must be permanent, not temporary gists, localhost endpoints, or volatile storage. The manifest example in plugins/zoom/README.md references a fixed raw GitHub URL to ensure the plugin store cache remains valid after initial ingestion.

Required Schema Structure

The OpenAI platform enforces strict structural validation. Your schema must include these top-level sections:

• info object: Must contain title and version fields for display in the plugin store and version tracking.

• servers array: Requires at least one entry specifying the HTTPS base URL for all API calls. The Zoom OpenAPI files (openapi.v2.json) demonstrate this pattern with a single server entry that the platform uses as the base for all path invocations.

• paths definitions: Each HTTP method must specify responses containing at least one 200-class response. If the endpoint accepts request bodies, a valid request schema is required. This enables the platform to generate reliable request/response types for the language model.

• components section: Define reusable schemas, security schemes, and response models here to keep the specification DRY. The Zoom plugin schema uses components for shared model definitions across multiple paths.

Security and Authentication

If your API requires authentication, the schema must declare a security scheme in components.securitySchemes using standard OpenAPI types: apiKey, oauth2, or http with bearer scheme.

Operations requiring authentication must reference the security scheme in their security arrays. The OAuth implementation patterns shown in plugins/zoom/skills/general/use-cases/ai-integration.md align with this requirement, demonstrating how the platform surfaces authentication flows to users and injects credentials securely at runtime.

Validation Constraints and Limits

The platform performs strict validation beyond basic schema parsing:

• Resolvable references: All $ref pointers must resolve to definitions within the same document or to publicly reachable URLs. Internal references must follow the #/components/... pattern. Broken external references cause hard validation failures.

• File size limits: The specification must remain under a few megabytes. Large specifications strain the validation pipeline; repository examples like the Zoom openapi.v2.json remain well below this threshold to ensure quick loading.

• Complete operation definitions: Every path must include fully-specified response schemas. Incomplete definitions prevent the platform from generating accurate function signatures for the language model.

Configuring the Plugin Manifest

The plugin manifest (.codex-plugin/plugin.json) connects the OpenAI platform to your schema via the api field. The manifest must reference the HTTPS URL of your validated OpenAPI file.

{
  "name": "my-awesome-plugin",
  "description": "A plugin that talks to MyService.",
  "auth": {
    "type": "service_http",
    "authorization_type": "bearer"
  },
  "api": {
    "type": "openapi",
    "url": "https://raw.githubusercontent.com/myorg/my-awesome-plugin/main/openapi.yaml"
  },
  "logo_url": "https://myorg.com/logo.png",
  "contact_email": "support@myorg.com"
}

This configuration demonstrates the required api.type value of "openapi" and the url pointing to a CORS-enabled, HTTPS-hosted schema file that meets all platform requirements.

Minimal OpenAPI Schema Example

Below is a complete, minimal OpenAPI specification that satisfies all platform requirements:

openapi: "3.0.1"
info:
  title: MyService API
  version: "1.0"
servers:
  - url: https://api.myservice.com/v1
paths:
  /items:
    get:
      summary: List items
      operationId: listItems
      responses:
        "200":
          description: A list of items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Item"
components:
  schemas:
    Item:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []

This example includes all required top-level fields (openapi, info, servers, paths, components), uses an internal $ref reference, declares a bearer token security scheme, and specifies an HTTPS server URL.

Summary

• Version: Must use OpenAPI 3.0.x or newer; Swagger 2.0 is rejected according to the openai/plugins source code.
• Hosting: HTTPS-only with valid TLS, CORS-enabled for cross-origin GET requests, and hosted at a stable, permanent URL.
• Structure: Must contain info (with title/version), servers (HTTPS base URL), paths (with 200-class responses), and components (for reusable schemas).
• Security: Declare schemes in components.securitySchemes and reference them in operation-level security arrays.
• Validation: All $ref pointers must resolve internally or to public URLs, file size must be under platform limits, and MIME types must be correct (application/json or application/yaml).

Frequently Asked Questions

What OpenAPI versions are supported by the OpenAI plugin platform?

The platform exclusively supports OpenAPI 3.0.x and newer specifications. Swagger 2.0 files are rejected during validation. As evidenced in plugins/zoom/skills/rest-api/references/openapi.md, legacy 2.0 schemas must be upgraded to 3.x format before plugin integration.

Can I use localhost or temporary URLs for my OpenAPI schema during development?

No. The platform requires a stable, publicly accessible HTTPS URL for the schema file. Temporary endpoints like GitHub gists or localhost references will fail validation because the plugin store caches the schema for production use. Use a permanent raw GitHub URL or dedicated hosting as shown in plugins/zoom/README.md.

How do I configure authentication in my OpenAPI schema?

Define a security scheme in components.securitySchemes using types like bearer, apiKey, or oauth2. Then reference that scheme in each protected operation's security array. According to plugins/zoom/skills/general/use-cases/ai-integration.md, this configuration enables the platform to surface authentication flows to users and inject credentials securely at runtime.

What happens if my schema contains references to external files?

All $ref pointers must resolve to definitions within the same document or to publicly reachable URLs. The platform fetches the entire document during validation; unresolved or privately hosted external references cause hard validation failures. Keep references internal using #/components/schemas/ paths when possible, as demonstrated in the Zoom plugin OpenAPI specifications.

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