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

> Master OpenAPI schema requirements for OpenAI plugins. Ensure your plugin is discoverable and functional by validating info, servers, paths, and security schemes in your OpenAPI 3.x spec.

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

---

**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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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.

```json
{
  "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:

```yaml
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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.