# What Information Does a Marketplace JSON Entry Contain? > Discover what information a marketplace JSON entry holds for plugins. Learn about identity, source, auth, and UI metadata in this structured object. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: api-reference - Published: 2026-09-12 --- **A marketplace JSON entry defines a single plugin's identity, source location, installation policy, authentication requirements, and optional UI metadata through a structured JSON object stored in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json).** The `openai/plugins` repository manages plugin distribution for OpenAI Codex through a centralized registry. Each **marketplace JSON entry** specifies the essential metadata required for the runtime to discover, validate, and surface plugins to users according to the source code definitions. ## Core Structure of a Marketplace JSON Entry The canonical source of truth resides in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json). According to the repository implementation, each entry follows a standardized schema containing six top-level keys that describe where the plugin's code lives, how it is installed, what authentication model it uses, and the functional category it belongs to. The structure includes: - `name`: Unique identifier for the plugin - `source`: Code location and retrieval method configuration - `policy`: Installation availability and authentication rules - `category`: High-level functional classification - `interface`: Optional user-facing display metadata ## Required Fields in a Marketplace JSON Entry ### name The `name` field serves as the unique identifier for the plugin within the marketplace. This value must be distinct across all entries in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) and is used as the internal reference by the Codex runtime. Example: `"name": "linear"` ### source The `source` object specifies where the plugin code resides and how to retrieve it. The object requires a `source` key indicating the retrieval method, with additional keys varying by type. The repository supports three retrieval methods: - **local**: References a directory inside the repository using a `path` relative to the repository root - **url**: Points to an external Git repository via a `url` string - **git-subdir**: Targets a specific subdirectory within a remote Git repository using both `url` and `path` keys ### policy The `policy` object governs the plugin's lifecycle and access controls through required and optional sub-fields: - **installation**: Defines availability status. The value `"AVAILABLE"` allows users to discover and install the plugin through the marketplace interface. - **authentication**: Specifies when user credentials are required. Values include `"ON_INSTALL"` (required during initial setup) or `"ON_USE"` (required at runtime when invoking the plugin). - **products** (optional): Restricts the plugin to specific OpenAI products. For example, `["CODEX"]` limits availability to the Codex environment. ### category The `category` field assigns a high-level classification for UI organization in the marketplace. Common values found in the source include `"Productivity"`, `"Developer Tools"`, `"Communication"`, and `"Creativity"`. ## Optional Interface Metadata ### displayName and UI Fields The optional `interface` object contains user-facing presentation data. The primary field is `displayName`, which provides a human-readable label shown in the marketplace UI instead of the technical `name` value. Additional UI metadata such as icons and descriptions may be included within this object to enhance the marketplace presentation, though these fields are not required for functional plugin operation. ## Source Configuration Examples Different source types require specific field combinations as implemented in the repository. ### Local Plugin Configuration For plugins stored within the `openai/plugins` repository itself: ```json { "name": "gmail", "source": { "source": "local", "path": "./plugins/gmail" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "Communication" } ``` ### Remote URL Plugin For external Git repositories where the plugin resides at the root: ```json { "name": "crowdstrike-falcon-foundry", "source": { "source": "url", "url": "https://github.com/CrowdStrike/foundry-skills.git" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "Developer Tools", "interface": { "displayName": "CrowdStrike Falcon Foundry" } } ``` ### Git-Subdir Plugin For repositories containing multiple plugins in specific subdirectories: ```json { "name": "qodo", "source": { "source": "git-subdir", "url": "https://github.com/qodo-ai/qodo-skills.git", "path": "codex-packages/qodo" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "Developer Tools", "interface": { "displayName": "Qodo" } } ``` ## Related Configuration Files While [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) serves as the master registry, the ecosystem includes supplementary files that support the marketplace infrastructure. The file [`.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/api_marketplace.json) defines API-level capabilities and runtime validation schemas used by the Codex system to process marketplace requests. Additionally, individual plugin directories may contain `plugins/*/.app.json` files with application-specific metadata such as app IDs that may be referenced by the corresponding marketplace entries. ## Summary - Each **marketplace JSON entry** in `openai/plugins` is defined in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) and requires `name`, `source`, `policy`, and `category` fields. - The `source` object supports three retrieval modes: **local**, **url**, and **git-subdir**, each requiring different location parameters (`path` for local/git-subdir, `url` for remote sources). - **Installation policies** control availability through `policy.installation` (set to `"AVAILABLE"` to enable), while `policy.authentication` determines whether credentials are required `"ON_INSTALL"` or `"ON_USE"`. - Optional `interface` metadata provides human-readable `displayName` values and UI customization data to enhance marketplace presentation. - The `policy.products` array can restrict plugins to specific OpenAI products such as `["CODEX"]`. ## Frequently Asked Questions ### What file contains the marketplace JSON entries for OpenAI plugins? The master registry resides at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) in the `openai/plugins` repository. This file serves as the single source of truth for all plugins available through the Codex marketplace, containing the complete structured list of plugin metadata entries that the runtime uses for discovery and validation. ### What is the difference between "url" and "git-subdir" source types? The **url** source type points to the root of a Git repository, treating the entire repository content as the plugin source code. The **git-subdir** source type specifies both a repository `url` and a `path` subdirectory within that repository, allowing multiple plugins to reside in different folders of a single external repository while targeting only the relevant subdirectory for installation. ### How do you restrict a plugin to specific OpenAI products? Use the optional `policy.products` array field in the marketplace JSON entry. By including specific product identifiers such as `["CODEX"]` in this array, the entry limits installation and usage to users of those designated OpenAI products, preventing the plugin from appearing in unsupported platforms or environments. ### Is the interface field required for all marketplace entries? No, the `interface` field is optional. While required fields including `name`, `source`, `policy`, and `category` must be present for the entry to function in the Codex runtime, the `interface` object only needs to be included when providing user-facing display metadata such as `displayName`, icons, or descriptions that enhance the marketplace presentation layer.