Understanding the Relationship Between .app.json App Definitions and Plugin Interface Configuration

In the OpenAI Plugins repository, .app.json files declare runtime connector IDs for backend services while the interface object in plugin.json defines how the plugin appears in ChatGPT, with the latter referencing the former via a relative path to establish the complete plugin manifest.

The OpenAI Plugins architecture separates runtime connectivity from user-facing presentation through a dual-manifest system. Understanding the relationship between .app.json app definitions and plugin interface configuration is essential for building integrations that route correctly to backend services while rendering properly in the ChatGPT UI.

The Role of .app.json in Runtime Connectivity

The .app.json file serves as the runtime app definition, mapping human-readable app names to connector IDs that the OpenAI platform understands. This file focuses exclusively on backend connectivity.

Located in the plugin root (e.g., plugins/google-drive/.app.json), this JSON file contains an apps object where each key represents an app identifier and each value contains the corresponding connector ID:

{
  "apps": {
    "google-drive": {
      "id": "connector_5f3c8c41a1e54ad7a76272c89e2554fa"
    }
  }
}

According to the repository source code, this connector ID tells the OpenAI platform which backend service to invoke when the plugin executes an action. The file contains no presentation logic—only the runtime routing information required to connect to external APIs.

The Interface Configuration in plugin.json

While .app.json handles backend connectivity, the interface object inside plugin.json (located in the .codex-plugin subdirectory) controls presentation and behavior in the ChatGPT UI.

As implemented in plugins/google-drive/.codex-plugin/plugin.json, the interface configuration includes fields such as:

• displayName: The human-readable name shown in the plugin store
• shortDescription: The subtitle or summary text
• capabilities: An array defining supported interaction modes (e.g., ["Interactive"], ["Write"])
• logo: Path to the plugin's icon asset
• category: Classification for the plugin marketplace
• defaultPrompt: Suggested prompts presented to users

This metadata informs ChatGPT how to render plugin cards, handle user interactions, and display branding elements, but contains no information about which backend connector to use.

How the Manifests Link Together

The relationship between these two files is established through a relative path reference in plugin.json. The apps field in plugin.json points to the .app.json file location:

{
  "name": "google-drive",
  "apps": "./.app.json",
  "interface": {
    "displayName": "Google Drive",
    "shortDescription": "Manage and search your Google Drive files",
    "capabilities": ["Interactive"]
  }
}

This linkage creates a separation of concerns that allows the OpenAI platform to:

1. Render the UI using the interface metadata (display name, logos, descriptions)
2. Execute actions by resolving the connector ID defined in .app.json

When a user activates the plugin, ChatGPT first reads the interface configuration to display the plugin card and capabilities. When the user triggers an action, the platform follows the apps reference to locate the connector ID in .app.json and route the request to the correct backend service.

Real-World Examples from the Repository

This architectural pattern remains consistent across all plugins in the repository. The following table illustrates the relationship in production plugins:

Plugin	App Definition Path	Interface Configuration Path
Google Drive	plugins/google-drive/.app.json	plugins/google-drive/.codex-plugin/plugin.json
Notion	plugins/notion/.app.json	plugins/notion/.codex-plugin/plugin.json
Vercel	plugins/vercel/.app.json	plugins/vercel/.codex-plugin/plugin.json
Zoom	plugins/zoom/.app.json	plugins/zoom/.codex-plugin/plugin.json

In each case, the .app.json file contains only the connector ID mapping, while the plugin.json file contains the interface object defining display metadata and points back to the app definition via the "apps": "./.app.json" field.

Summary

• .app.json declares runtime connectivity by mapping app names to connector IDs for backend service routing.
• plugin.json contains the interface object that controls ChatGPT UI presentation, including display names, icons, capabilities, and descriptions.
• The apps field in plugin.json creates the link between presentation and runtime by referencing .app.json via a relative path.
• Together, these files enable the OpenAI platform to present plugins correctly in the UI while routing actions to the appropriate backend connectors.

Frequently Asked Questions

What is the difference between .app.json and the interface object in plugin.json?

The .app.json file focuses solely on runtime connectivity, containing connector IDs that tell the OpenAI platform which backend service to invoke. The interface object in plugin.json focuses on presentation and behavior, defining how the plugin appears in ChatGPT through fields like displayName, shortDescription, and capabilities.

How does plugin.json reference the .app.json file?

The plugin.json file uses a relative path in its apps field to point to the .app.json location, typically "apps": "./.app.json". This tells the OpenAI platform to load the connector IDs defined in that specific file when installing or executing the plugin.

What specific fields does the interface configuration control in ChatGPT?

The interface configuration controls the plugin card appearance and interaction capabilities, including displayName (the plugin title), shortDescription (the summary text), logo (the icon asset), category (marketplace classification), and capabilities (supported interaction modes like Interactive or Write).

Where are these configuration files located in the plugin directory structure?

The .app.json file resides in the plugin root directory (e.g., plugins/google-drive/.app.json), while the plugin.json file containing the interface configuration resides in the .codex-plugin subdirectory (e.g., plugins/google-drive/.codex-plugin/plugin.json).

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