Claude API rejects tool schemas: missing 'required' field causes 'JSON schema is invalid' error

[1186258278]

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

1. Install OpenCode with oh-my-opencode plugin
2. Configure a custom provider using @ai-sdk/openai-compatible pointing to a new-api instance
3. Select claude-opus-4-6-thinking as the model
4. 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_list with original schema → 400 error
• session_list with "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

[github-actions]

This issue appears to be a duplicate or closely related to several existing issues that report the same root cause—missing required field in tool schemas:

• JSON Schema validation fails on empty tool parameters {} with Kimi K2.5 (strict mode error) #11357: JSON Schema validation fails on empty tool parameters {} with Kimi K2.5
• Strict JSON Schema validation fail on backends like SGLang (Missing required field in empty tool parameters) #8184: Strict JSON Schema validation fail on backends like SGLang (Missing required field in empty tool parameters)
• LiteLLM Proxy: Vertex AI Gemini models fail for tools with empty parameters #9233: LiteLLM Proxy: Vertex AI Gemini models fail for tools with empty parameters
• [bug] Gemini schema sanitization misses properties/required when type is undefined #13148: Gemini schema sanitization misses properties/required when type is undefined

All of these report that when tool schemas have properties but are missing the required field, 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 in ProviderTransform.schema() that handles the schema sanitization comprehensively across all providers.

[yangxiaolin9527]

@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 read tool, an error JSON schema is invalid. It must match JSON Schema draft 2020-12 is 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]

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.2