--json-schema rejects schemas declaring the draft 2020-12 meta-schema (since 2.1.214)

Status Open
Reported on v2.1.218
Maintainer reply None cached
Activity 1 comment · opened Jul 23, 2026

Environment

  • Claude Code 2.1.218 (also confirmed on 2.1.215/2.1.216 in CI); regression window points at 2.1.214 ("Fixed --json-schema silently producing unstructured output when the schema was invalid")
  • macOS (darwin) and Linux (aarch64), non-interactive -p mode

Bug

--json-schema hard-fails schema validation when the schema's $schema key declares the JSON Schema draft 2020-12 meta-schema:

$ echo '{}' | claude -p "Reply with a JSON object with key ok set to true" \
    --json-schema '{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}'
Error: --json-schema is not a valid JSON Schema: no schema with key or ref "https://json-schema.org/draft/2020-12/schema"

The identical schema declared as draft-07 works and enforces correctly:

$ echo '{}' | claude -p "Reply with a JSON object with key ok set to true" \
    --json-schema '{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}'
{"ok":true}

The error message is Ajv's "no schema with key or ref" — i.e. the 2020-12 meta-schema isn't registered with the validator (Ajv's default instance only knows draft-07; 2020-12 needs the Ajv2020 class or explicit meta-schema registration).

Why this matters

Draft 2020-12 is the default output dialect of current schema generators — Rust's schemars 1.x stamps "$schema": "https://json-schema.org/draft/2020-12/schema" on every schema, and other ecosystems are similar. Anthropic's own tool-definition schemas declare 2020-12. Before 2.1.214 these schemas were silently tolerated (validation quietly fell back to unstructured output); 2.1.214 correctly made invalid schemas loud, but that turned every generator-default schema into a hard failure. In our case it broke a CI agent pipeline at the final step of every run for several days.

Expected

Either resolve the 2020-12 (and 2019-09) meta-schemas so $schema dialect declarations from modern generators work, or ignore the advisory $schema key rather than failing resolution on it.

Workaround

Emit draft-07 schemas (e.g. schemars::generate::SchemaSettings::draft07()) or strip the top-level $schema key before passing the schema.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗