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

Managing OpenAI plugin marketplace entries requires editing the 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 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 file located at the repository root (/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.

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. Ensure the plugin folder contains the required assets referenced by the entry.

Example entry structure:

{
  "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:

node scripts/validate-marketplace.js

This script imports the schema from 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. 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:

// 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 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 file resides at the repository root (/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, 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 that demonstrates bulk tagging operations across all entries.

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