Where to Find the marketplace.json Schema for Claude Plugins

The canonical marketplace.json schema for Claude plugins is defined as a Zod validation object located in .github/actions/validate-plugins/lib/schema.ts within the anthropics/claude-plugins-community repository.

The anthropics/claude-plugins-community repository maintains a strict JSON schema that governs how plugins are published to the Claude marketplace. Understanding where to find the marketplace.json schema is essential for developers who want to submit new plugins or validate existing configurations against the official specification.

Location of the Schema Definition

The schema is implemented using Zod (TypeScript-first schema validation with static type inference). According to the source code, the definitive schema lives at:

.github/actions/validate-plugins/lib/schema.ts

This file contains the Zod object definitions that enforce the shape of every plugin entry in the marketplace file. The validation rules require the root object to contain a top-level plugins array, where each entry must conform to the strict field requirements defined in this schema.

Schema Structure and Field Requirements

The Zod schema enforces specific data types and constraints for plugin metadata. When constructing your marketplace.json file, each plugin object must satisfy these validation rules.

Required Fields

Every plugin entry must include these mandatory properties:

• name (string): A unique identifier following the format owner/repo-name or similar namespace convention
• description (string): A human-readable summary of the plugin's functionality
• source (object): Contains either a github URL with a pinned sha commit hash, or a direct url pointing to a zipped plugin archive
• version (string): Semantic versioning (semver) string representing the plugin release

The schema strictly enforces HTTPS URLs only and requires SHA pinning for external repository sources to ensure supply chain security. It also disallows shell metacharacters in file names to prevent injection attacks.

Optional Fields

Plugin authors may also include these optional metadata fields:

• homepage (string): URL to the plugin's documentation or landing page
• icon (string): Path or URL to the plugin's icon asset
• license (string): SPDX license identifier or license name
• tags (array): Categorization labels for discoverability in the marketplace

Validating Your marketplace.json Locally

Before submitting to the community repository, you can validate your marketplace.json file against the official schema using the Claude CLI:

claude plugin validate marketplace.json

This command runs the same Zod validation logic that the CI pipeline executes, checking for required fields, URL formats, SHA pinning compliance, and security constraints on file names.

Related Validation Infrastructure

Several files in the repository work together to enforce schema compliance:

• .github/actions/validate-plugins/lib/schema.ts: The Zod schema definition that specifies validation logic
• .github/actions/validate-plugins/README.md: Documentation explaining invariant rules (I1-I11) that rely on the Zod schema
• .claude-plugin/marketplace.json: The assembled marketplace file that serves as the live example of schema-compliant entries
• .github/workflows/validate-plugins.yml: The GitHub Actions workflow that automatically runs schema validation on every pull request

Summary

• The marketplace.json schema is defined as a Zod object in .github/actions/validate-plugins/lib/schema.ts
• Root object must contain a plugins array with specific required fields: name, description, source, and version
• Validation enforces HTTPS URLs, SHA pinning for GitHub sources, and security constraints on file names
• Use claude plugin validate marketplace.json to check compliance before submitting
• The CI pipeline runs automatically via .github/workflows/validate-plugins.yml on all PRs

Frequently Asked Questions

What file contains the actual Zod schema definition for Claude plugins?

The Zod schema is located at .github/actions/validate-plugins/lib/schema.ts in the anthropics/claude-plugins-community repository. This TypeScript file exports the validation object that defines required fields, data types, and constraints for every plugin entry in the marketplace.

What fields are mandatory in the marketplace.json schema?

Every plugin entry must include four required fields: name (unique identifier string), description (human-readable summary), source (object with either GitHub URL + pinned SHA or direct archive URL), and version (semver string). The schema rejects any entries missing these properties.

How do I validate my plugin entry against the schema before submitting?

Run the Claude CLI command claude plugin validate marketplace.json locally. This executes the same Zod validation rules used by the GitHub Actions workflow, checking field types, URL formats, SHA pinning requirements, and security constraints.

Does the schema allow HTTP URLs or Git branches instead of commit SHAs?

No. The schema strictly enforces HTTPS URLs only and requires SHA pinning for GitHub repository sources. It does not accept HTTP URLs or branch names in the source object, ensuring reproducible builds and preventing supply chain attacks.

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