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

The 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 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.

Schema Location and Validation Workflow

The canonical schema resides in .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, ensuring that all entries in .claude-plugin/marketplace.json meet security and formatting standards.

The schema is consumed by the CI pipeline defined in .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.

{
  "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 schema is implemented as a Zod object in .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, 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. This file exports the validation logic used by the CI workflow to check .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. 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.

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