# Claude Plugins Community marketplace.json Schema: Complete Field Reference

> Explore the Claude Plugins Community marketplace.json schema. Understand all required and optional fields for plugin submissions, including name, description, URL, and source details. Submit your plugin today.

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

---

**The [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) schema defines a top-level `plugins` array containing plugin entries with required fields `name`, `description`, `url`, and a nested `source` object with `repo` and `sha` properties, plus optional fields like `homepage`, `tags`, `icon`, `license`, `authors`, and `dependencies`.**

The **marketplace.json** file serves as the canonical manifest for all community-published Claude plugins in the `anthropics/claude-plugins-community` repository. This JSON file powers the plugin marketplace UI and installation system, with strict schema enforcement handled through Zod-based validation in CI.

## marketplace.json Structure Overview

The file contains a single top-level object with one required key:

| Key | Type | Description |
|-----|------|-------------|
| `plugins` | array | List of all registered community plugins |

Every entry in the `plugins` array must conform to the schema enforced by the **validate-plugins** GitHub Action.

## Required Fields for Each Plugin Entry

Each plugin object must include these core properties:

### `name` (string)

The unique human-readable identifier for the plugin. This value must be globally unique across all marketplace entries and match certain filename conventions.

### `description` (string)

A concise summary displayed in the marketplace UI to help users understand the plugin's purpose.

### `url` (string, HTTPS)

The Git URL of the source repository. Must use HTTPS protocol. Example: `https://github.com/user/repo.git`

### `source` (object)

Specifies how the plugin code is fetched. This object requires:

- **`repo`** (string, HTTPS): Git URL matching the top-level `url` field
- **`sha`** (string): Exact commit SHA that the marketplace pins to for reproducible installs

Optional `source` subfield:
- **`subdir`** (string): Relative path inside the repository where the `.claude-plugin` directory resides

## Optional Fields for Plugin Entries

### `homepage` (string, HTTPS)

Public landing page URL for the plugin, typically a GitHub repository page.

### `tags` (array of strings)

Keywords enabling plugin discovery. Common values include `"devtools"`, `"prisma"`, `"zod"`, `"testing"`.

### `icon` (string, URL)

Direct link to an SVG or PNG icon displayed in the marketplace UI.

### `license` (string)

SPDX license identifier (e.g., `"MIT"`, `"Apache-2.0"`).

### `authors` (array of strings)

Names or GitHub handles of primary contributors.

### `dependencies` (object)

NPM-style dependency map that mirrors declarations in the plugin's [`package.json`](https://github.com/anthropics/claude-plugins-community/blob/main/package.json).

## Complete Example: marketplace.json Entry

Based on entries in [[`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json), a valid plugin entry looks like:

```json
{
  "plugins": [
    {
      "name": "prisma-zod-consistency",
      "description": "Audit Prisma + Zod + TypeScript projects for cross-layer drift...",
      "url": "https://github.com/rshelekhov/prisma-zod-consistency.git",
      "homepage": "https://github.com/rshelekhov/prisma-zod-consistency",
      "source": {
        "repo": "https://github.com/rshelekhov/prisma-zod-consistency.git",
        "sha": "a1b2c3d4e5f6g7h8i9j0k..."
      },
      "tags": ["devtools", "prisma", "zod"],
      "icon": "https://raw.githubusercontent.com/rshelekhov/prisma-zod-consistency/main/icon.svg"
    }
  ]
}

```

## Schema Enforcement and Validation

The **marketplace.json schema** is validated through a multi-layer CI process defined in `.github/actions/validate-plugins/`.

### Validation Checks

Per the action's [README.md](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md), which states the Zod schema is the "source of truth for the marketplace/plugin schema", the validator enforces:

- All required fields present (`name`, `description`, `url`, `source.repo`, `source.sha`)
- HTTPS-only URLs for security
- SHA pinning (no floating version tags allowed)
- Filename-to-entry name consistency
- No shell metacharacters in string fields
- Global uniqueness of plugin names

### CI Validation Script

The validation executes through [[`.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh)](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh):

```bash
#!/bin/bash

# Validates marketplace.json against the Claude CLI schema

claude plugin validate .claude-plugin/marketplace.json

```

The action configuration in [[`.github/actions/validate-plugins/action.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/action.yml)](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/action.yml) orchestrates this validation on every pull request.

## Working with marketplace.json Programmatically

### Adding a Plugin Entry via Command Line

```bash
jq '.plugins += [{
  "name": "my-cool-plugin",
  "description": "Do something awesome with Claude",
  "url": "https://github.com/me/my-cool-plugin.git",
  "source": {
    "repo": "https://github.com/me/my-cool-plugin.git",
    "sha": "abc123def456789"
  },
  "tags": ["cool", "demo"]
}]' .claude-plugin/marketplace.json > tmp.json && mv tmp.json .claude-plugin/marketplace.json

```

### Reading Plugin Data in Node.js

```javascript
const fs = require('fs');

const market = JSON.parse(
  fs.readFileSync('.claude-plugin/marketplace.json', 'utf8')
);

const entry = market.plugins.find(p => p.name === 'my-cool-plugin');
console.log(entry.source.sha);  // exact pinned commit

```

### Validating Locally

```bash
claude plugin validate .claude-plugin/marketplace.json

```

## Key Files Defining the Schema

| File | Purpose |
|------|---------|
| [[`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) | Live marketplace manifest with all plugin entries |
| [[`.github/actions/validate-plugins/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md)](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md) | Documents the Zod schema as source of truth |
| [[`.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh)](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh) | CLI validation execution script |
| [[`.github/actions/validate-plugins/action.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/action.yml)](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/action.yml) | GitHub Action configuration for CI enforcement |

## Summary

- The **marketplace.json schema** centers on a `plugins` array containing standardized plugin objects
- **Required fields**: `name`, `description`, `url`, `source.repo`, `source.sha`
- **Optional fields**: `homepage`, `source.subdir`, `tags`, `icon`, `license`, `authors`, `dependencies`
- **SHA pinning** in `source.sha` ensures reproducible installations
- **Zod-based validation** in the `validate-plugins` GitHub Action enforces schema compliance before merge
- All URL fields must use **HTTPS protocol** for security

## Frequently Asked Questions

### Where is the marketplace.json schema officially defined?

The schema is officially defined in the **validate-plugins GitHub Action** using Zod. According to [[`.github/actions/validate-plugins/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md)](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md), the Zod definition serves as the "source of truth for the marketplace/plugin schema". The actual validation runs through `claude plugin validate` as implemented in [[`.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh)](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh).

### Why does source.sha use exact commits instead of version tags?

The `source.sha` field requires exact commit SHAs to guarantee **reproducible installations**. Floating version tags could change downstream, leading to inconsistent plugin behavior or security issues. This immutable pinning ensures every installation retrieves identical code.

### What happens if my marketplace.json entry fails validation?

The CI job fails and blocks merge. The **validate-plugins** action runs on every pull request via [[`.github/actions/validate-plugins/action.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/action.yml)](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/action.yml), checking for required fields, HTTPS URLs, SHA format, name uniqueness, and prohibited characters. Fix reported errors and push updates to pass validation.

### Can I specify a subdirectory for my plugin files?

Yes. Use the **`source.subdir`** field to indicate a relative path inside your repository where the `.claude-plugin` directory lives. This supports monorepo structures where multiple packages or plugins exist in subdirectories.