Guaranteed JSON Schema Compliance for Claude Code Output

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code cannot guarantee output matches a specific JSON schema. --output-format json returns Claude Code's wrapper structure, with actual data nested inside:

{
  "messages": [...],
  "result": {
    "content": [{"type": "text", "text": "{\"countries\": [...]}"}]
  }
}

Users must extract and validate the nested JSON against their schema. Tool calling improves reliability but doesn't guarantee 100% schema compliance, requiring validation and error handling in production pipelines.

Proposed Solution

Add a --json-schema flag that enforces schema compliance via constrained decoding:

claude -p "List countries with capitals" \
  --output-format json \
  --json-schema countries.schema.json

The nested response content is guaranteed to match the provided JSON schema.

Alternative Solutions

1. Tool calling enhancement: Add --strict-schema flag to existing tool calling mechanism
2. New output format: --output-format strict-json that takes schema as input
3. Configuration file: Schema definitions in .claude/schemas/ directory

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

Schema file (countries.schema.json):

{
  "type": "array",
  "items": {
    "type": "object",
    "required": ["country", "capital"],
    "properties": {
      "country": {"type": "string"},
      "capital": {"type": "string"}
    }
  }
}

Command:

claude -p "List 3 countries with capitals" \
  --output-format json \
  --json-schema countries.schema.json | jq '.result.content[0].text | fromjson'

Guaranteed output format:

[
  {"country": "France", "capital": "Paris"},
  {"country": "Germany", "capital": "Berlin"},
  {"country": "Japan", "capital": "Tokyo"}
]

Can pipe directly to databases, APIs, or processing scripts without validation.

Additional Context

Current workarounds:

• Manual validation with libraries like json-repair
• Retry loops with error handling
• Careful prompting (unreliable)

Comparison:
OpenAI provides this via Structured Outputs with strict: true flag, guaranteeing 100% schema compliance at token generation level.

Related issues: #586, #2904, #3383

Benefits:

• Eliminates validation code in production
• Enables reliable CI/CD automation
• Reduces error handling complexity