# How to Manage Plugin Marketplace Entries Using marketplace.json in OpenAI Plugins

> Learn to manage OpenAI plugin marketplace entries by editing marketplace.json. Validate your changes using provided scripts for seamless updates.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-07-04

---

**Managing OpenAI plugin marketplace entries requires editing the [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file at the repository root, which defines a JSON array of plugin metadata, and validating changes against the schema using the provided Node.js scripts before committing.**

The `openai/plugins` repository uses a centralized configuration file to control which plugins appear in the Plugin Marketplace. By managing the [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file, repository maintainers can add, update, hide, or remove plugin listings through simple JSON edits and version control workflows.

## Understanding the marketplace.json Structure

The [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file located at the repository root ([`/marketplace.json`](https://github.com/openai/plugins/blob/main//marketplace.json)) serves as the single source of truth for all marketplace listings. It contains a JSON array where each object represents a single plugin entry that must conform to the schema defined in [`schema/marketplace.schema.json`](https://github.com/openai/plugins/blob/main/schema/marketplace.schema.json).

### Required Entry Fields

Each marketplace entry must include specific properties to be considered valid:

- **id**: Unique identifier using lowercase, hyphen-separated format
- **name**: Human-readable plugin name displayed in the UI
- **description**: Short summary appearing on the marketplace card
- **logoUrl**: HTTPS URL to a 256×256 PNG or SVG (typically hosted in the plugin's folder)
- **auth**: Authentication configuration object specifying type and scopes
- **api**: Object containing paths to `openapi` and `manifest` files

### Optional Configuration Properties

Additional fields provide enhanced control over listing visibility and discoverability:

- **homepage**: URL linking to documentation or the plugin's website
- **hidden**: Boolean flag to exclude entries from public display while retaining them in version control
- **tags**: Array of strings for categorization and search functionality

## Adding a New Plugin Entry

To introduce a new plugin to the marketplace, append a new object to the JSON array in [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json). Ensure the plugin folder contains the required assets referenced by the entry.

Example entry structure:

```json
{
  "id": "my-awesome-plugin",
  "name": "My Awesome Plugin",
  "description": "Provides AI-powered insights for your CRM.",
  "logoUrl": "https://github.com/openai/plugins/raw/main/plugins/my-awesome-plugin/logo.png",
  "homepage": "https://github.com/openai/plugins/tree/main/plugins/my-awesome-plugin",
  "auth": {
    "type": "oauth",
    "scopes": ["contacts.read", "contacts.write"]
  },
  "api": {
    "openapi": "plugins/my-awesome-plugin/openapi.yaml",
    "manifest": "plugins/my-awesome-plugin/manifest.json"
  },
  "tags": ["crm", "insights"],
  "hidden": false
}

```

After adding the entry, commit the corresponding `logo.png` file to `plugins/my-awesome-plugin/` so the `logoUrl` resolves correctly.

## Validating Changes with the Marketplace Validator

Before submitting changes, run the validation script to ensure your edits comply with the JSON schema. The validator checks for missing required fields, malformed URLs, and schema violations.

Execute the validator from the repository root:

```bash
node scripts/validate-marketplace.js

```

This script imports the schema from [`schema/marketplace.schema.json`](https://github.com/openai/plugins/blob/main/schema/marketplace.schema.json) and outputs "✅ marketplace.json is valid" or a detailed list of errors requiring correction.

## Modifying and Removing Entries

Updates to existing plugins require editing the specific fields within the corresponding JSON object in [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json). For temporary removal or beta testing, set the `hidden` property to `true` rather than deleting the entry entirely. This preserves the configuration while preventing public visibility.

To permanently remove a plugin, delete its object from the array and run the validator to ensure the remaining JSON structure is intact.

## Automating Bulk Updates

For maintenance tasks like adding standardized tags across all entries, use the programmatic helper utilities. Create a Node.js script that reads, modifies, and writes the marketplace configuration:

```javascript
// scripts/update-marketplace.js
const fs = require('fs');
const path = './marketplace.json';
const entries = JSON.parse(fs.readFileSync(path, 'utf8'));

// Add a tag to every entry
entries.forEach(entry => {
  entry.tags = Array.from(new Set([...(entry.tags || []), 'openai']));
});

fs.writeFileSync(path, JSON.stringify(entries, null, 2));
console.log('✅ marketplace.json updated');

```

Run the script with `node scripts/update-marketplace.js`, then validate and commit the changes.

## Summary

- The [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file at the repository root controls all Plugin Marketplace listings in the `openai/plugins` repository.
- Each entry must include `id`, `name`, `description`, `logoUrl`, `auth`, and `api` fields, with optional `hidden` and `tags` properties.
- Validate all changes using `node scripts/validate-marketplace.js` before committing.
- Use the `hidden` boolean flag to temporarily remove entries without deleting configuration data.
- Programmatic updates can be scripted using standard Node.js file system operations against the JSON array.

## Frequently Asked Questions

### Where is the marketplace.json file located in the openai/plugins repository?

The [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file resides at the repository root ([`/marketplace.json`](https://github.com/openai/plugins/blob/main//marketplace.json)). This location serves as the definitive configuration source that the marketplace UI and registry services load on startup.

### What happens if I don't run the validator before committing changes?

Unvalidated changes may cause CI pipeline failures or runtime errors in the marketplace service. The validator ensures all entries conform to [`schema/marketplace.schema.json`](https://github.com/openai/plugins/blob/main/schema/marketplace.schema.json), preventing broken plugin listings from reaching production.

### Can I temporarily hide a plugin without deleting its entry?

Yes. Set the `hidden` property to `true` within the plugin's JSON object. This excludes the entry from the public marketplace while preserving the configuration in version control for future reactivation or internal testing.

### How do I update multiple marketplace entries at once?

Create a Node.js script utilizing `fs.readFileSync` and `fs.writeFileSync` to manipulate the JSON array programmatically. The repository provides an example pattern in [`scripts/update-marketplace.js`](https://github.com/openai/plugins/blob/main/scripts/update-marketplace.js) that demonstrates bulk tagging operations across all entries.