[DOCS] Plugin schema docs omit validator-accepted `$schema` and top-level marketplace metadata

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/plugin-marketplaces

Section/Topic

Marketplace schema, Marketplace validation errors, and the plugin manifest schema in the plugins reference

Current Documentation

The marketplace schema currently lists only these required top-level fields:

| name | string | Marketplace identifier (kebab-case, no spaces). This is public-facing: users see it when installing plugins (for example, /plugin install my-tool@your-marketplace). | | owner | object | Marketplace maintainer information ([see fields below](#owner-fields)) | | plugins | array | List of available plugins |

The same page documents marketplace description and version only under metadata:

| metadata.description | string | Brief marketplace description | | metadata.version | string | Marketplace version | | metadata.pluginRoot | string | Base directory prepended to relative plugin source paths (for example, "./plugins" lets you write "source": "formatter" instead of "source": "./plugins/formatter") |

The validation warnings also point users to metadata.description:

No marketplace description provided: add metadata.description to help users understand your marketplace

The plugin manifest reference currently shows a complete plugin.json schema beginning with:

``json { "name": "plugin-name", "version": "1.2.0", "description": "Brief plugin description", "author": { ``

Its metadata fields table lists version, description, author, homepage, repository, license, and keywords, but no $schema field.

What's Wrong or Missing?

Changelog v2.1.120 says:

claude plugin validate now accepts $schema, version, and description at the top level of marketplace.json and $schema in plugin.json

The current docs are now outdated in two related schema locations:

A. marketplace.json top-level accepted fields are missing

The marketplace schema tells authors to use metadata.description and metadata.version, and the validation warning specifically says to add metadata.description. It does not document that description, version, or $schema are accepted at the top level of marketplace.json.

B. plugin.json $schema support is missing

The plugin manifest schema and metadata table do not mention $schema, so plugin authors have no documented way to know that adding a JSON Schema URL to .claude-plugin/plugin.json is accepted by claude plugin validate.

C. Validation guidance can steer users away from valid files

Because the validation docs still frame metadata.description as the expected marketplace description location, authors using the newly accepted top-level description may think their file is non-canonical even though the validator now accepts it.

Suggested Improvement

Update the marketplace schema to list the newly accepted top-level fields:

• $schema: optional JSON Schema URL for editor autocomplete and validation
• description: optional brief marketplace description
• version: optional marketplace version string

Clarify how top-level description/version relate to the existing metadata.description and metadata.version fields, including which form is preferred and whether both are supported for backward compatibility.

Update the marketplace examples and validation warning to use the preferred form, for example:

{
"$schema": "https://...",
"name": "company-tools",
"description": "Internal developer tools",
"version": "1.0.0",
"owner": {
"name": "DevTools Team"
},
"plugins": []
}

Also update the plugin manifest schema in plugins-reference to include optional $schema at the top level of .claude-plugin/plugin.json, and add it to the metadata fields table with the same editor-autocomplete framing used by other Claude Code JSON files.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/plugin-marketplaces | Marketplace schema lists metadata.description and metadata.version, but not top-level $schema, description, or version; validation warning still says to add metadata.description |
| https://code.claude.com/docs/en/plugins-reference | Plugin manifest schema and metadata fields omit top-level $schema in .claude-plugin/plugin.json |
| https://code.claude.com/docs/en/plugins | Introductory plugin manifest example omits $schema; could link to the full manifest schema once updated |

Total scope: 3 pages affected

Source: Changelog v2.1.120

Exact changelog entry: claude plugin validate now accepts $schema, version, and description at the top level of marketplace.json and $schema in plugin.json