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

> Discover the relationship between app.json app definitions and plugin interface configuration in the OpenAI Plugins repository. Learn how these files define connector IDs and plugin appearance.

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

---

**In the OpenAI Plugins repository, [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) files declare runtime connector IDs for backend services while the `interface` object in [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/.app.json) handles backend connectivity, the **`interface` object** inside [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.json). The `apps` field in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) points to the [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file location:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/google-drive/.app.json) | [`plugins/google-drive/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/google-drive/.codex-plugin/plugin.json) |
| **Notion** | [`plugins/notion/.app.json`](https://github.com/openai/plugins/blob/main/plugins/notion/.app.json) | [`plugins/notion/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/notion/.codex-plugin/plugin.json) |
| **Vercel** | [`plugins/vercel/.app.json`](https://github.com/openai/plugins/blob/main/plugins/vercel/.app.json) | [`plugins/vercel/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/vercel/.codex-plugin/plugin.json) |
| **Zoom** | [`plugins/zoom/.app.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.app.json) | [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json) |

In each case, the [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file contains only the connector ID mapping, while the [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.app.json)** declares runtime connectivity by mapping app names to connector IDs for backend service routing.
- **[`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)** contains the `interface` object that controls ChatGPT UI presentation, including display names, icons, capabilities, and descriptions.
- The **`apps` field** in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) creates the link between presentation and runtime by referencing [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.json) file uses a relative path in its `apps` field to point to the [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.app.json) file resides in the **plugin root directory** (e.g., [`plugins/google-drive/.app.json`](https://github.com/openai/plugins/blob/main/plugins/google-drive/.app.json)), while the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file containing the interface configuration resides in the **`.codex-plugin` subdirectory** (e.g., [`plugins/google-drive/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/google-drive/.codex-plugin/plugin.json)).