# Claude Plugin marketplace.json Schema: Zod Validation Structure and Required Fields

> Discover the Claude plugin marketplace.json schema. Learn about Zod validation and required fields like name, description, source, and version with strict HTTPS and SHA pinning.

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

---

**The [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) schema for Claude plugins is defined as a Zod validation object in the repository's `validate-plugins` GitHub Action, requiring a root `plugins` array where each entry contains `name`, `description`, `source`, and `version` properties with strict HTTPS and SHA-pinning constraints.**

The **anthropics/claude-plugins-community** repository maintains the official schema for validating Claude plugin entries submitted to the community marketplace. Understanding the [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) schema is essential for developers who want to publish plugins that pass automated CI validation. The schema enforces security and metadata standards through a TypeScript Zod definition located in [`.github/actions/validate-plugins/lib/schema.ts`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/schema.ts).

## Schema Location and Validation Workflow

The canonical schema resides in [`.github/actions/validate-plugins/lib/schema.ts`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/schema.ts) within the `anthropics/claude-plugins-community` repository. This TypeScript module exports a **Zod** object that defines the exact shape, types, and constraints for every plugin entry. The validation logic enforces eleven invariant rules (I1-I11) documented in [`.github/actions/validate-plugins/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/README.md), ensuring that all entries in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) meet security and formatting standards.

The schema is consumed by the CI pipeline defined in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml), which automatically validates pull requests against these rules before merging.

## Required Fields in the marketplace.json Schema

Every plugin object inside the root `plugins` array must include four mandatory properties:

- **`name`** (string): A unique identifier following the `owner/repo` format, such as `anthropic/example-plugin`.
- **`description`** (string): A concise human-readable summary of the plugin's functionality.
- **`version`** (string): A semantic version number (semver) indicating the plugin release.
- **`source`** (object): Defines the plugin's distribution method through one of two mutually exclusive patterns.

The `source` object requires either a `github` property containing a repository URL with a pinned `sha` commit hash, or a direct `url` pointing to a zipped plugin archive. Both methods enforce **HTTPS-only** URLs to prevent man-in-the-middle attacks.

```json
{
  "plugins": [
    {
      "name": "anthropic/example-plugin",
      "description": "A sample Claude plugin",
      "version": "1.0.0",
      "source": {
        "github": "https://github.com/anthropic/example-plugin",
        "sha": "a1b2c3d4e5f6..."
      }
    }
  ]
}

```

## Source Object Structure and Security Constraints

The **Zod schema** implements strict security policies for the `source` property. You must specify exactly one distribution method:

**GitHub Source Method:**
- **`github`** (string): HTTPS URL to the GitHub repository.
- **`sha`** (string): Full commit hash pinning the exact version.

**Direct URL Method:**
- **`url`** (string): HTTPS URL to a zipped plugin archive.

The schema rejects HTTP URLs and requires SHA pinning for GitHub sources to prevent supply-chain attacks. It also disallows shell metacharacters in file paths to block command injection vulnerabilities.

## Optional Metadata Fields

Beyond required properties, the schema accepts optional fields to enhance marketplace presentation:

- **`homepage`** (string): HTTPS URL for documentation or landing pages.
- **`icon`** (string): URL to a square icon image.
- **`license`** (string): SPDX identifier or license name.
- **`tags`** (array): Descriptive strings for categorization.

These optional fields inherit the same HTTPS enforcement and character restrictions as required properties.

## Summary

- The **[`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) schema** is implemented as a Zod object in [`.github/actions/validate-plugins/lib/schema.ts`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/schema.ts).
- Each plugin entry requires **`name`**, **`description`**, **`version`**, and **`source`** properties within a root `plugins` array.
- The **`source`** object supports GitHub URLs with **SHA pinning** or direct **HTTPS archive URLs** exclusively.
- Validation occurs via [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml), enforcing HTTPS-only URLs and shell-safe filenames.
- Optional fields include **`homepage`**, **`icon`**, **`license`**, and **`tags`** for enhanced metadata.

## Frequently Asked Questions

### What file defines the schema for Claude plugin marketplace entries?

The schema is defined in **TypeScript using Zod** in [`.github/actions/validate-plugins/lib/schema.ts`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/schema.ts). This file exports the validation logic used by the CI workflow to check [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) against eleven invariant security and formatting rules.

### How do I specify the source code location for my Claude plugin?

Use the **`source`** object with either a `github` property containing the repository URL and a pinned `sha` hash, or a `url` property pointing to a zipped plugin archive. The schema requires HTTPS URLs and rejects uncommitted branch references to ensure reproducible builds.

### Can I use HTTP URLs in my marketplace.json entry?

No. The Zod schema explicitly enforces **HTTPS-only** URLs for all external references, including `source` locations, `homepage`, and `icon` fields. Entries containing HTTP links fail validation and block pull request merges in the `anthropics/claude-plugins-community` repository.

### Where can I see an example of a valid marketplace.json file?

The repository includes a working example at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json). This file demonstrates the proper structure with the required `plugins` array containing properly formatted plugin objects that pass the validation rules enforced by the schema in the `validate-plugins` action.