工具调用（tool / function calling）JSON Schema 不合法

[hem951740-max]

Problem (one or two sentences)

在v3.37.1中，调用claude模型报错：Date/time: 2025-12-24T05:18:08.508Z
Extension version: 3.37.1
Provider: openai
Model: claude-sonnet-4-5

400
OpenAI completion error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"..custom.input_schema: JSON schema is invalid. It must match JSON Schema draft 2020-12 (https://.org//*** Learn more about tool use at https://.com///；切换会3.36版本就不会有这样的错误

Context (who is affected and when)

在v3.37.1中，调用claude模型报错：Date/time: 2025-12-24T05:18:08.508Z
Extension version: 3.37.1
Provider: openai
Model: claude-sonnet-4-5

400
OpenAI completion error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"..custom.input_schema: JSON schema is invalid. It must match JSON Schema draft 2020-12 (https://.org//*** Learn more about tool use at https://.com///；切换会3.36版本就不会有这样的错误

Reproduction steps

在v3.37.1中，调用claude模型报错：Date/time: 2025-12-24T05:18:08.508Z
Extension version: 3.37.1
Provider: openai
Model: claude-sonnet-4-5

400
OpenAI completion error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"..custom.input_schema: JSON schema is invalid. It must match JSON Schema draft 2020-12 (https://.org//*** Learn more about tool use at https://.com///；切换会3.36版本就不会有这样的错误

Expected result

在v3.37.1中，调用claude模型报错：Date/time: 2025-12-24T05:18:08.508Z Extension version: 3.37.1 Provider: openai Model: claude-sonnet-4-5 400 OpenAI completion error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"..custom.input_schema: JSON schema is invalid. It must match JSON Schema draft 2020-12 (https://.org//*** Learn more about tool use at https://.com///；切换会3.36版本就不会有这样的错误

Actual result

在v3.37.1中，调用claude模型报错：Date/time: 2025-12-24T05:18:08.508Z Extension version: 3.37.1 Provider: openai Model: claude-sonnet-4-5 400 OpenAI completion error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"..custom.input_schema: JSON schema is invalid. It must match JSON Schema draft 2020-12 (https://.org//*** Learn more about tool use at https://.com///；切换会3.36版本就不会有这样的错误v

Variations tried (optional)

No response

App Version

v3.37.1

API Provider (optional)

None

Model Used (optional)

No response

Roo Code Task Links (optional)

No response

Relevant logs or errors (optional)

[roomote]

I have analyzed this issue and identified the root cause.

Problem Analysis

The error "JSON schema is invalid. It must match JSON Schema draft 2020-12" occurs because:

1. Several native tool definitions use type arrays like type: ["string", "null"] or type: ["array", "null"] for nullable parameters (e.g., in read_file.ts, execute_command.ts, browser_action.ts, etc.)

2. This type array syntax is valid in JSON Schema draft-07, but NOT in JSON Schema draft 2020-12 (which requires using anyOf format instead)

3. While src/utils/json-schema.ts has a normalizeToolSchema function that properly converts type arrays to anyOf format, it is only used by specific providers (Bedrock, VSCode LM)

4. The OpenAI-compatible provider uses convertToolSchemaForOpenAI in src/api/providers/base-provider.ts, which attempts to handle nullable types but does not properly convert them to the anyOf format required by JSON Schema draft 2020-12

5. In v3.37.1, the OpenAI handler now sends native tool definitions by default (commit 6afc59b), which exposed this schema incompatibility for third-party proxies that enforce JSON Schema draft 2020-12

Proposed Implementation Plan

1. Modify convertToolSchemaForOpenAI in src/api/providers/base-provider.ts to use the existing normalizeToolSchema function from src/utils/json-schema.ts which already properly handles:

   • Converting type: ["T", "null"] array syntax to anyOf format
   • Moving array-specific properties (items, minItems, etc.) inside the array variant when using anyOf
   • Recursively processing nested schemas

2. Update tests to verify that tool schemas are properly normalized for JSON Schema draft 2020-12 compliance

This approach:

• Reuses the existing, well-tested normalization logic
• Ensures consistency across all providers that use the OpenAI-compatible format
• Fixes the issue for all tool definitions at once without modifying individual tool files

Please mention @roomote in a comment saying that you approve this plan, and I will proceed with the implementation.

[hem951740-max]

@roomote 批准

[roomote]

Thanks for the approval! I will now proceed with the implementation to fix the JSON Schema compatibility issue. I will open a PR shortly to share progress.

[roomote]

Opened #10321 with my attempt at addressing this. The fix updates convertToolSchemaForOpenAI in base-provider.ts to use the existing normalizeToolSchema function, which properly converts type arrays like ["string", "null"] to anyOf format required by JSON Schema draft 2020-12. Feedback welcome!

[hem951740-max]

@roomote 那意思是我现在必须要回退版本使用吗，你们为什么不能吧xml个原生像之前一样开放使用呢

[roomote]

I have seen your comment. You raise a valid point about needing a workaround while the fix is pending.

Current Situation:

• PR fix: ensure JSON Schema draft 2020-12 compliance for OpenAI-compatible providers #10321 has been submitted to fix the JSON Schema compatibility issue
• The XML tool protocol was deprecated in recent versions - resolveToolProtocol.ts now always returns Native protocol regardless of user settings
• This means there is currently no setting to switch back to XML mode

Your Options:

1. Recommended: Downgrade to v3.36 temporarily until PR fix: ensure JSON Schema draft 2020-12 compliance for OpenAI-compatible providers #10321 is merged and released
2. Wait for PR fix: ensure JSON Schema draft 2020-12 compliance for OpenAI-compatible providers #10321 to be reviewed and merged (it fixes the JSON Schema draft 2020-12 compliance issue)

Regarding why XML mode was removed: it was deprecated as part of a broader effort to use native tool calling which is generally more reliable and supported by modern APIs. However, I understand this created an issue for users of certain proxies that enforce strict JSON Schema validation.

The fix in PR #10321 should resolve the compatibility issue without needing to revert to XML mode, as it properly converts type arrays to the anyOf format required by JSON Schema draft 2020-12.