# What Are the Limitations on Claude Plugin Response Formats?

> Understand Claude plugin response format limitations. Learn how Claude strictly requires JSON data under 40KB validating against a schema, rejecting other formats.

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

---

**Claude plugins must return strictly JSON data under 40 KB that validates against a predefined schema, rejecting any HTML, Markdown, or non-UTF-8 content.**

The `anthropics/claude-plugins-community` repository enforces a rigid contract for plugin communication to ensure the Claude model can parse responses reliably and securely. Every plugin response must conform to a JSON-only format with specific structural constraints defined in the repository’s configuration files.

## Core Response Constraints

### JSON Structure Requirements

Responses must be a single, well-formed JSON object. The platform validates the payload before passing it to the model, and any structural deviation causes immediate rejection.

Key structural rules include:

- **Top-level object required**: The root element must be an object (`{ … }`). Primitive values (strings, numbers, booleans, null) or arrays as the root element are invalid.
- **No circular references**: The JSON graph must be acyclic; self-referencing structures cause validation failures.
- **UTF-8 encoding only**: The entire payload must be valid UTF-8. Non-UTF-8 byte sequences trigger parsing errors.

### Payload Size and Transport Limits

Performance and security constraints impose strict size limits on plugin responses:

- **40 KB maximum**: The entire JSON payload may not exceed approximately 40 000 characters (40 KB). Exceeding this limit results in truncation or a hard error.
- **Content-Type header**: When served over HTTP, responses must include the header `Content-Type: application/json`. Any other MIME type causes the request to be rejected.

## Content and Schema Restrictions

### Prohibited Formats

The platform sanitizes all output to prevent injection attacks and ensure consistent rendering:

- **No HTML or Markdown**: Even text fields must contain plain text without markup. The model handles presentation logic; plugins cannot inject formatting.
- **Binary data encoding**: Raw binary data is not permitted. Files such as images must be encoded as Base64 strings or referenced via URLs within the JSON object.

### Schema Validation via plugin.json

Each plugin declares its response contract in [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json). The platform enforces this schema strictly:

- **Required fields**: Missing keys defined as required in the schema cause validation errors.
- **Ignored extra fields**: Additional properties not declared in the schema are silently ignored.
- **Type enforcement**: Values must match the declared types (string, number, boolean, object, array) exactly.

The repository’s [`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md) links to these schema definitions, while [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) aggregates the schemas for all listed community plugins.

## Valid Response Structure Examples

Below are minimal, compliant payloads that satisfy all constraints.

**Simple text reply:**

```json
{
  "type": "text",
  "content": "Your account balance is $1,245.67."
}

```

**Image result with URL reference:**

```json
{
  "type": "image",
  "url": "https://example.com/generated-chart.png",
  "alt": "Bar chart of monthly expenses"
}

```

Both examples use a top-level object, contain only allowed primitive types, omit markup, and remain well under the 40 KB limit.

## Summary

- **JSON-only**: Responses must be single, well-formed JSON objects; no arrays or primitives at the root.
- **Size cap**: Hard limit of 40 KB (≈ 40 000 characters) per response.
- **Plain text**: HTML and Markdown are prohibited; use plain text only.
- **Schema-driven**: Validity depends on the [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) schema declared in `.claude-plugin/` directories.
- **Encoding**: UTF-8 is mandatory; binary data requires Base64 encoding.
- **HTTP headers**: `Content-Type: application/json` is required for network-delivered plugins.

## Frequently Asked Questions

### What is the maximum size for a Claude plugin response?

The platform enforces a strict limit of **40 KB** (approximately 40 000 characters) for the entire JSON payload. Exceeding this size causes the response to be rejected or truncated, as defined in the repository’s validation logic referenced in [`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md).

### Can Claude plugins return HTML or Markdown formatting?

No. Plugins must return **plain text only** inside JSON strings. The model handles all presentation rendering internally, and any HTML tags or Markdown syntax in the payload will be treated as literal text or cause validation errors.

### How are images and binary files handled in plugin responses?

Binary data cannot be returned raw. Images and files must be either **embedded as Base64-encoded strings** within a JSON field or **referenced by URL**. The [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) schema for each plugin in `.claude-plugin/` directories defines which fields accept these references.

### Where is the response schema defined for a Claude plugin?

Each plugin declares its response structure in **[`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json)** within its directory. The aggregate list of community plugins and their schemas resides in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json). The repository’s [`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md) provides high-level documentation linking to these schema files.