# Claude Plugins Community marketplace.json File Format: Complete Schema Guide

> Understand the marketplace.json file format for Claude plugins. This guide details the complete schema, including required and optional fields for plugin metadata.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: api-reference
- Published: 2026-08-28

---

**The [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file is a JSON array containing plugin metadata objects with required fields like `name`, `description`, `version`, `author`, `repository`, and `manifestPath`, plus optional fields for icons, checksums, tags, visibility, and licensing.**

The [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file serves as the canonical catalogue for all community-published Claude plugins in the `anthropics/claude-plugins-community` repository. Located at [`/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main//.claude-plugin/marketplace.json), this single JSON document powers the plugin marketplace UI and is strictly validated by continuous integration workflows to ensure every entry conforms to the expected schema.

## Core Schema and Required Fields

Each element in the [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) array represents a distinct plugin entry. The following fields are mandatory for every plugin listing:

- **`name`** – Human-readable identifier (e.g., `"Preserve Session"`)
- **`description`** – Full description displayed in the marketplace interface
- **`version`** – Semantic version string (e.g., `"1.2.3"`)
- **`author`** – Individual or organization responsible for the plugin
- **`repository`** – Absolute URL to the GitHub repository hosting the source code
- **`manifestPath`** – Relative path to the plugin's [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) file (e.g., `".claude-plugin/plugin.json"`)

A minimal valid entry appears as:

```json
{
  "name": "Preserve Session",
  "description": "Keeps Claude Code sessions alive across project moves, renames, and copies",
  "version": "1.0.0",
  "author": "anthropic",
  "repository": "https://github.com/anthropics/claude-plugins-community",
  "manifestPath": ".claude-plugin/plugin.json"
}

```

## Optional Metadata Fields

The schema supports additional fields to enhance discoverability and security:

- **`icon`** – URL or relative path to an SVG/PNG asset for the marketplace UI
- **`sha256`** – SHA-256 hash of the plugin bundle for integrity verification
- **`tags`** – Array of classification strings (e.g., `["finance", "analysis"]`) to aid search
- **`visibility`** – Access control string; either `"public"` (default) or `"private"`
- **`license`** – SPDX license identifier for the plugin's legal terms

## CI Validation and Schema Enforcement

The repository enforces schema compliance through automated validation defined in [`/.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main//.github/workflows/validate-plugins.yml). The CI executes `claude plugin validate <marketplace.json>` against the assembled catalogue, utilizing validation logic implemented in [`/.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main//.github/actions/validate-plugins/lib/common.sh).

Invalid entries—whether from missing required fields or malformed data types—cause the workflow to fail, preventing corrupted metadata from reaching the production marketplace. This gatekeeping ensures that every plugin referenced in [`/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main//.claude-plugin/marketplace.json) maintains data integrity and matches the structure defined in the corresponding [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifests.

## How to Parse marketplace.json Programmatically

Since the file is a standard JSON array, you can consume it using any language. Below are reference implementations for Node.js and Python.

### Loading the Catalogue in Node.js

```javascript
import fs from 'fs';
import path from 'path';

const marketplacePath = path.resolve('.claude-plugin/marketplace.json');
const raw = fs.readFileSync(marketplacePath, 'utf-8');
const plugins = JSON.parse(raw);

plugins.forEach(p => {
  console.log(`${p.name} – v${p.version}`);
});

```

### Filtering Plugins by Tag in Python

```python
import json
import pathlib

data = json.loads(pathlib.Path('.claude-plugin/marketplace.json').read_text())
finance_plugins = [p for p in data if 'finance' in p.get('tags', [])]

for p in finance_plugins:
    print(f"{p['name']} ({p['version']}): {p['description']}")

```

## Summary

- The [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file format is a **JSON array** located at [`/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main//.claude-plugin/marketplace.json) in the `anthropics/claude-plugins-community` repository.
- **Required fields** include `name`, `description`, `version`, `author`, `repository`, and `manifestPath`.
- **Optional fields** support `icon`, `sha256`, `tags`, `visibility`, and `license` metadata.
- The **CI validation workflow** in [`/.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main//.github/workflows/validate-plugins.yml) enforces schema compliance using `claude plugin validate`.
- Each entry's `manifestPath` points to a [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) file (typically at [`/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main//.claude-plugin/plugin.json)) that contains the actual plugin implementation details.

## Frequently Asked Questions

### What is the root structure of the marketplace.json file?

The root structure is a **JSON array** (`[...]`) where each element is a JSON object representing a single plugin. It is not a keyed object but a sequential list, allowing the marketplace to iterate through available plugins programmatically.

### Which fields are mandatory in the marketplace.json schema?

Six fields are strictly required: **`name`**, **`description`**, **`version`**, **`author`**, **`repository`**, and **`manifestPath`**. The CI validation脚本 in [`/.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main//.github/actions/validate-plugins/lib/common.sh) will reject any entry missing these core properties.

### How does the CI validate the marketplace.json file format?

The validation workflow runs automatically via [`/.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main//.github/workflows/validate-plugins.yml), executing the command `claude plugin validate` against the [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file. This process checks field presence, data types, and URL validity, failing the build if any entry violates the schema.

### What is the relationship between marketplace.json and plugin.json?

The [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file contains catalogue metadata and a **`manifestPath`** field that points to each plugin's individual **[`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)** file. While [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) tracks high-level information like versioning and tags for the marketplace UI, [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) (referenced via the manifest path) defines the plugin's runtime behavior and command specifications.