[DOCS] `--json-schema` flag docs omit v2.1.205 fix for invalid-schema silent fallback and `format` keyword rejection

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/headless

Section/Topic

The "Get structured output" section under "Examples" (the opening paragraph that introduces --json-schema, the two example invocations, and the surrounding jq tip). The matching --json-schema row in the CLI flags table on https://code.claude.com/docs/en/cli-reference is the second affected location.

Current Documentation

The "Get structured output" section of https://code.claude.com/docs/en/headless reads:

Use --output-format to control how responses are returned: text (default): plain text output json: structured JSON with result, session ID, and metadata * stream-json: newline-delimited JSON for real-time streaming This example returns a project summary as JSON with session metadata, with the text result in the result field: ``bash claude -p "Summarize this project" --output-format json ` To get output conforming to a specific schema, use --output-format json with --json-schema and a [JSON Schema](https://json-schema.org/) definition. The response includes metadata about the request (session ID, usage, etc.) with the structured output in the structured_output field. This example extracts function names and returns them as an array of strings: `bash claude -p "Extract the main function names from auth.py" \ --output-format json \ --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' ``

The matching CLI row in https://code.claude.com/docs/en/cli-reference reads:

| --json-schema | Get validated JSON output matching a JSON Schema after agent completes its workflow (print mode only, see structured outputs) | claude -p --json-schema '{"type":"object","properties":{...}}' "query" |

Neither location says what happens when the supplied schema is invalid, and neither shows a schema that uses the JSON Schema format keyword.

The Agent SDK structured outputs page (https://code.claude.com/docs/en/agent-sdk/structured-outputs, "Output format configuration" section, around line 240) enumerates SDK-supported features and links out to the API-side "JSON Schema limitations" section on platform.claude.com. That platform page lists nine supported string formats (date-time, time, date, duration, email, hostname, uri, ipv4, ipv6, uuid) and is the canonical reference for what format values are valid behind the API, but the CLI flag is treated as a separate surface and neither page connects the two.

What's Wrong or Missing?

A. The v2.1.205 fix for invalid-schema silent fallback is not reflected in the docs

The v2.1.205 changelog says:

Fixed --json-schema silently producing unstructured output when the schema was invalid, and schemas using the format keyword being rejected

Before v2.1.205, passing an invalid schema to --json-schema produced unstructured output (the user got a normal --output-format json payload with no structured_output, or a different shape than they asked for) instead of an error. After v2.1.205 the CLI should fail loudly so the caller can fix the schema. The "Get structured output" section in headless.md never states this contract: it describes the success path (a structured_output field appears) but says nothing about what to expect when the schema is malformed, and the matching CLI row in cli-reference.md uses the phrase "Get validated JSON output" without acknowledging that the validation now errors instead of silently degrading.

A user who relied on the v2.1.204 behavior to "see whatever came back" from a broken schema would have to know to read the changelog to understand why their pipeline now exits non-zero. The docs give them no hint.

B. The format keyword being accepted is not documented at the CLI surface

Before v2.1.205, the CLI rejected any schema that included the format keyword (e.g. "format": "date-time", "format": "email", "format": "uuid"), even though those formats are explicitly listed as supported by the underlying API on the platform docs. After v2.1.205 the CLI accepts them.

The headless.md example schema deliberately avoids format ({type, properties, required} only). The CLI row's example placeholder ({"type":"object","properties":{...}}) is also format-free. The Agent SDK structured outputs page lists supported SDK features in prose and links to the platform limitations section, but says nothing specific to the CLI --json-schema flag, so a user who tried to add a format field on a v2.1.204 install and got an error has no place in the Claude Code docs to look that confirms format is now supported.

C. The two behaviors are coupled in one changelog line but documented as one feature

The two halves of the v2.1.205 changelog entry — invalid-schema surfacing and format acceptance — are part of the same fix to the structured-output contract on the CLI, but the user-facing docs only ever describe that contract as "validated JSON output matching a JSON Schema." A user who upgrades and starts getting errors for invalid schemas, or starts seeing format constraints pass validation, gets no signal from the docs that this was a deliberate change in v2.1.205.

Suggested Improvement

Add a short follow-on paragraph to the "Get structured output" section on https://code.claude.com/docs/en/headless (after the current jq tip) that:

• States explicitly that an invalid schema causes the CLI to error rather than return unstructured output, and that this is the v2.1.205 behavior. Use a min-version: 2.1.205 marker so older clients see the original prose.
• Names the JSON Schema format keyword as accepted, and links to the JSON Schema limitations section on the platform docs for the full list of supported format values. Mark the change with the same min-version: 2.1.205 marker.
• Optionally extends the example to use one format value, for example adding created_at: {type: "string", format: "date-time"} to a new example, so a reader sees the syntax inline.

The matching --json-schema row in https://code.claude.com/docs/en/cli-reference should get a min-version: 2.1.205 annotation noting that invalid schemas now error and that the format keyword is supported, parallel to how the --permission-mode row on the same page notes the v2.1.200 manual alias addition.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/headless | 115-138 | "Get structured output" section: intro paragraph, two example invocations, and the jq tip |
| https://code.claude.com/docs/en/cli-reference | 91 | --json-schema row in the CLI flags table |

Total scope: 2 pages affected

Related surfaces (cross-references):

• https://code.claude.com/docs/en/agent-sdk/structured-outputs — the SDK-side structured outputs page; its "Output format configuration" section around line 240 enumerates supported JSON Schema features and points at the platform limitations section, but does not address the CLI flag specifically.
• https://platform.claude.com/docs/en/build-with-claude/structured-outputs#json-schema-limitations — the platform page lists nine supported string format values (date-time, time, date, duration, email, hostname, uri, ipv4, ipv6, uuid) at line 2980; the CLI fix in v2.1.205 brings the CLI surface into line with what the API documentation has always claimed.

Version: The fix described in the v2.1.205 changelog applies to Claude Code v2.1.205 and later. Users on v2.1.204 and earlier will still see the old behavior (silent fallback on invalid schemas, format rejection).

Why this is one root cause: Both halves of the v2.1.205 changelog entry — silent fallback on invalid schema, and format keyword rejection — are part of the same structured-output contract change for the CLI flag. The same docs location (headless.md plus the matching cli-reference.md row) covers both, so they belong in a single issue.