Repository navigation
Claude API rejects tool schemas: missing 'required' field causes 'JSON schema is invalid' error #13618
Description
Bug Description
When using OpenCode with Claude models (especially thinking models like claude-opus-4-6-thinking) through an OpenAI-compatible proxy (e.g., new-api), the API returns:
***.custom.input_schema: JSON schema is invalid. It must match JSON Schema draft 2020-12
This happens because some tool schemas generated by plugins (e.g., oh-my-opencode's session_list) have properties but no required field. Claude API strictly requires required to be present when properties exists, even if it's an empty array [].
Steps to Reproduce
- Install OpenCode with oh-my-opencode plugin
- Configure a custom provider using
@ai-sdk/openai-compatiblepointing to a new-api instance - Select
claude-opus-4-6-thinkingas the model - Send any message
Root Cause
Two issues in packages/opencode/src/provider/transform.ts → ProviderTransform.schema():
1. Missing required field (primary cause)
Plugin tools like session_list generate schemas like:
{
"type": "object",
"properties": { "limit": { "type": "number" } },
"additionalProperties": false
}Claude API requires required to be present when properties exists. The thinking models are especially strict about this.
2. $schema meta field from Zod 4
Zod 4's toJSONSchema() adds "$schema": "https://json-schema.org/draft/2020-12/schema" to every schema output. While this may not always cause errors, it's a non-standard field for input_schema.
Note: The codebase already handles this for createStructuredOutputTool (line ~687 in prompt.ts: const { $schema, ...toolSchema } = input.schema), but the general ProviderTransform.schema() function doesn't strip it.
Proposed Fix
Add sanitization at the top of ProviderTransform.schema() in packages/opencode/src/provider/transform.ts:
export function schema(model: Provider.Model, schema: JSONSchema.BaseSchema | JSONSchema7): JSONSchema7 {
// Strip $schema meta field from Zod 4 toJSONSchema() output
if ("$schema" in schema) {
const { $schema: _, ...rest } = schema as any
schema = rest as JSONSchema.BaseSchema
}
// Claude API (especially thinking models) requires "required" when "properties" exists
const s = schema as any
if (s.type === "object" && s.properties && !s.required) {
s.required = []
}
// ... existing code ...
}Verification
Tested by intercepting OpenCode's API requests with a proxy, isolating all 33 tools, and testing each individually:
session_listwith original schema → 400 errorsession_listwith"required": []added → 200 OK- All 33 tools together after fix → 200 OK
Environment
- OpenCode: v1.2.1
- oh-my-opencode: v3.5.3
- Model: claude-opus-4-6-thinking (via new-api OpenAI-compatible proxy)
- OS: macOS 26.2 (Apple Silicon) / Windows 11
Related
- Similar issue in Claude Code: [BUG] JSON schema is invalid. It must match JSON Schema draft 2020-12 anthropics/claude-code#586
Activity
fix: sanitize tool JSON schemas for Claude API compatibility
github-actions commentedon Feb 14, 2026
This issue appears to be a duplicate or closely related to several existing issues that report the same root cause—missing
requiredfield in tool schemas:All of these report that when tool schemas have
propertiesbut are missing therequiredfield, various providers (Claude via proxy, SGLang, Vertex AI Gemini, Kimi K2.5) reject the schema as invalid.The fix you've proposed (adding
required: []when properties exists) aligns with the solutions discussed in the related issues above. This should be consolidated into a single fix inProviderTransform.schema()that handles the schema sanitization comprehensively across all providers.yangxiaolin9527 commentedon Mar 13, 2026
@1186258278, I think I'm having the same problem as you. OpenCode-1.2.25 with omo-slim and superpowers plugins. The configured model is Claude-opus-4.6. When calling the
readtool, an errorJSON schema is invalid. It must match JSON Schema draft 2020-12is thrown. I want to try your method, but I lack the knowledge in this area and I'm a bit hesitant to let the LLM help me. Can I directly modify it in a local file, or should I download its source code locally and reinstall it myself? Can you tell me what to do? Thx~iongion commentedon Mar 26, 2026
gpt 5.4 from openai has this
Invalid schema for function 'docker_create_container': In context=('properties', 'ports', 'anyOf', '0', 'additionalProperties', 'anyOf', '2'), array schema missing items.opencode
1.3.2github-actions commentedon Jun 26, 2026
To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.