# Default Marketplace JSON File Structure in OpenAI Plugins

> Discover the default marketplace JSON file structure in OpenAI plugins. Understand the layout for curated plugin catalogs, metadata, source paths, and installation policies.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: api-reference
- Published: 2026-09-12

---

**The default marketplace configuration is stored in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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

```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

```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

```bash
#!/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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json)**: The primary default marketplace definition for the OpenAI-curated catalog
- **[`.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/api_marketplace.json)**: Alternative marketplace configuration used for API-only scenarios
- **[`README.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/marketplace.json) file defines the standard OpenAI-curated plugin catalog used in full platform deployments, while [`api_marketplace.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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.