Default Marketplace JSON File Structure in OpenAI Plugins

The default marketplace configuration is stored in .agents/plugins/marketplace.json and defines the OpenAI-curated plugin catalog with fields for marketplace metadata and an array of plugin descriptors including source paths, installation policies, and categories.

The openai/plugins repository uses a centralized JSON configuration to define its built-in marketplace. This file serves as the primary source of truth for which plugins are available, their installation requirements, and their organizational structure when the platform initializes.

File Location and Purpose

The repository’s default marketplace definition is located at .agents/plugins/marketplace.json relative to the repository root. According to the source code and top-level README (line 10), this file enumerates the plugins bundled with the OpenAI-curated marketplace. It is referenced by the plugin loader at runtime to discover available plugins and enforce defined policies.

A separate configuration, .agents/plugins/api_marketplace.json, provides an alternative marketplace definition specifically for API-only scenarios.

JSON Schema and Structure

The marketplace JSON follows a hierarchical schema with top-level metadata and a nested array of plugin descriptors.

Top-Level Marketplace Metadata

The root object contains identifying information for the marketplace itself:

• name: The machine-readable marketplace identifier (openai-curated)
• interface.displayName: The human-readable label shown to users (Codex official)

Plugin Descriptor Objects

The plugins array contains objects with the following properties:

• name: The short plugin identifier (e.g., linear, slack)
• source: An object indicating a local source and the filesystem path relative to the repository root (e.g., ./plugins/<plugin>)
• policy: An object defining installation availability (AVAILABLE) and authentication timing (ON_INSTALL)
• category: A logical grouping for UI organization (e.g., Productivity, Communication)

How to Access and Parse the File

You can programmatically read the marketplace configuration using standard file I/O operations in various environments.

Reading with Node.js

import fs from 'fs';
import path from 'path';

const marketplacePath = path.resolve(__dirname, '..', '.agents', 'plugins', 'marketplace.json');
const marketplace = JSON.parse(fs.readFileSync(marketplacePath, 'utf8'));

console.log('Marketplace name:', marketplace.name);
console.log('Available plugins:', marketplace.plugins.map(p => p.name));

Parsing with Python

import json
from pathlib import Path

marketplace_file = Path(__file__).parent.parent / ".agents" / "plugins" / "marketplace.json"
with marketplace_file.open() as f:
    data = json.load(f)

slack_cfg = next(p for p in data["plugins"] if p["name"] == "slack")
print("Slack source path:", slack_cfg["source"]["path"])
print("Slack category:", slack_cfg["category"])

Querying via Command Line

#!/usr/bin/env bash
file=".agents/plugins/marketplace.json"
plugins=$(jq -r '.plugins[].name' "$file")
echo "Plugins in the default marketplace:"
echo "$plugins"

Related Configuration Files

• .agents/plugins/marketplace.json: The primary default marketplace definition for the OpenAI-curated catalog
• .agents/plugins/api_marketplace.json: Alternative marketplace configuration used for API-only scenarios
• README.md: Documents the marketplace location at line 10 and provides high-level repository context

Summary

• The default marketplace JSON file resides at .agents/plugins/marketplace.json in the openai/plugins repository
• It defines the openai-curated marketplace with a name field and human-readable interface.displayName
• The plugins array contains descriptors with name, source (local path), policy (availability and auth mode), and category fields
• The file is the runtime source of truth for plugin discovery and policy enforcement

Frequently Asked Questions

Where is the default marketplace JSON file located?

The file is located at .agents/plugins/marketplace.json relative to the repository root. This path is hardcoded as the primary source of truth for the built-in marketplace and is referenced in the repository's README.

What is the difference between marketplace.json and api_marketplace.json?

The marketplace.json file defines the standard OpenAI-curated plugin catalog used in full platform deployments, while api_marketplace.json provides an alternative configuration specifically designed for API-only scenarios where different plugin availability or policies may be required.

What authentication modes are supported in the policy field?

According to the source structure, the policy object includes an authentication mode field set to ON_INSTALL, indicating that authentication credentials are requested at the time of plugin installation rather than at first use or runtime.

How do I add a new plugin to the default marketplace?

To register a new plugin, add an entry to the plugins array in .agents/plugins/marketplace.json specifying the plugin name, local source path (e.g., ./plugins/your-plugin), installation policy (set to AVAILABLE), and appropriate category classification.

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