|
| 1 | +--- |
| 2 | +id: 003 |
| 3 | +title: "JSON Schema sanitization for Gemini functionDeclarations across reference bridges" |
| 4 | +date: 2026-09-03 |
| 5 | +summary: "How CLIProxyAPI, gemini-cli, opencode, and claude-code-router/@musistudio/llms sanitize JSON Schema before sending tool definitions to Gemini / Antigravity, and specifically what each does with a tuple array (prefixItems, no items)." |
| 6 | +tags: [gemini, antigravity, json-schema, tool-calling, cliproxyapi, gemini-cli, opencode, prefixitems] |
| 7 | +--- |
| 8 | + |
| 9 | +# JSON Schema sanitization for Gemini functionDeclarations |
| 10 | + |
| 11 | +Question: how do reference implementations sanitize JSON Schema before emitting Gemini |
| 12 | +`functionDeclarations`, and do they handle `{"type":"array","prefixItems":[...]}` with no `items`? |
| 13 | + |
| 14 | +## 1. router-for-me/CLIProxyAPI (@ d577e630) |
| 15 | + |
| 16 | +All cleaning lives in one file: `internal/util/gemini_schema.go`. Four entry points share |
| 17 | +`cleanJSONSchema(jsonStr, jsonSchemaCleanOptions)`: |
| 18 | + |
| 19 | +| Function | Options | |
| 20 | +|---|---| |
| 21 | +| `CleanJSONSchemaForGemini` | `addMissingArrayItems`, `removeGeminiMetadata`, `flattenUnions`, `forceEnumStringType` | |
| 22 | +| `CleanJSONSchemaForAntigravity` / `...Tool(_, requirePlaceholder)` | `addPlaceholder`, `addMissingArrayItems`, `antigravitySemantics`, `flattenUnions`, `dropAllEnums` | |
| 23 | +| `CleanJSONSchemaForAntigravityResponse` | `antigravitySemantics`, `flattenUnions`, `dropBooleanEnums`, `preserveAdditionalPropertiesFalse` (no `addMissingArrayItems`) | |
| 24 | + |
| 25 | +Pipeline (`cleanJSONSchema`): normalize malformed nodes → inline `$ref` / ref hints → `const`→`enum` |
| 26 | +→ enum→string → enum/additionalProperties/constraint hints → merge `if/then/else`, `allOf` → flatten |
| 27 | +`anyOf`/`oneOf` → flatten type arrays → remove unsupported keywords → cleanup `required` → empty-schema |
| 28 | +placeholder. |
| 29 | + |
| 30 | +Removed outright (`removeUnsupportedKeywords`): `$schema`, `$defs`, `definitions`, `const`, `$ref`, |
| 31 | +`$id`, `additionalProperties`, `propertyNames`, `patternProperties`, `if`, `then`, `else`, `$comment`, |
| 32 | +`enumDescriptions`, `enumTitles`, `prefill`, `deprecated`, `encrypted`, all `x-*`, plus `not` for |
| 33 | +Antigravity. Moved into `description` then deleted (`unsupportedConstraints`): `minLength`, `maxLength`, |
| 34 | +`exclusiveMinimum`, `exclusiveMaximum`, `pattern`, `minItems`, `maxItems`, `uniqueItems`, `contains`, |
| 35 | +`format`, `default`, `examples` (+ `minimum`, `maximum`, `multipleOf` for Antigravity). |
| 36 | + |
| 37 | +Tuple arrays: **`prefixItems` is never converted to `items` and never removed.** It is only recursed |
| 38 | +into for repair (`repairSchemaNode`, list keys `anyOf/oneOf/allOf/prefixItems`). Missing `items` is |
| 39 | +filled with a hardcoded string schema, independent of `prefixItems`: |
| 40 | + |
| 41 | +```go |
| 42 | +// Gemini and Antigravity reject tool array schemas without an items definition. |
| 43 | +if addMissingArrayItems && isArrayDeclaredType(clone["type"]) { |
| 44 | + if _, hasItems := clone["items"]; !hasItems { |
| 45 | + clone["items"] = map[string]any{"type": "string"} |
| 46 | + modified = true |
| 47 | + } |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | +So `{"type":"array","prefixItems":[{"type":"string"},{"type":"number"}]}` → |
| 52 | +`{"type":"array","prefixItems":[...],"items":{"type":"string"}}`. Response schemas keep the array with |
| 53 | +no `items` (test `TestCleanJSONSchema_ResponseArrayMissingItemsUnchanged`). |
| 54 | + |
| 55 | +Call sites: `translator/gemini/claude/gemini_claude_request.go:244`, |
| 56 | +`translator/gemini/openai/chat-completions/gemini_openai_request.go:361`, |
| 57 | +`translator/antigravity/claude/antigravity_claude_request.go:808`, |
| 58 | +`runtime/executor/antigravity_executor_request.go:209/235`, `util/responses_tools.go:308`. |
| 59 | +All emit `parametersJsonSchema`; the Antigravity executor later renames it to `parameters`. |
| 60 | + |
| 61 | +## 2. google-gemini/gemini-cli (@ 55b495d6) |
| 62 | + |
| 63 | +No tool-schema sanitizer at HEAD. MCP tool schemas pass through verbatim: |
| 64 | +`packages/core/src/tools/mcp-client.ts:1429` sets `parametersJsonSchema: this.toolDef.inputSchema`. |
| 65 | +`prefixItems` appears only in `packages/core/src/utils/schemaValidator.test.ts` (draft-2020-12 local |
| 66 | +validation via Ajv). The historical `sanitizeParameters` (in `tool-registry.ts`) is gone; forks still |
| 67 | +carry it (`ConardLi/easy-llm-cli`) and it only dropped `default` next to `anyOf` and non |
| 68 | +`enum`/`date-time` string `format` — no array/`items`/`prefixItems` logic ever. |
| 69 | + |
| 70 | +## 3. Others |
| 71 | + |
| 72 | +- **anomalyco/opencode** (@ f12e14cf) `packages/llm/src/protocols/utils/gemini-tool-schema.ts`: |
| 73 | + array with no `items` gets `items = {}`, and an item schema with no "schema intent" key gets |
| 74 | + `type: "string"`. `prefixItems` counts as schema intent but is NOT converted. The Moonshot |
| 75 | + projection in the sibling `tool-schema.ts` is the only one that does the real tuple conversion: |
| 76 | + `prefixItems` → `items` (single → that schema, many → `anyOf`), dropped if `items` already exists. |
| 77 | +- **musistudio/claude-code-router** (@ 5ad5083b): no schema code; transforms live in |
| 78 | + `@musistudio/llms`, `src/utils/gemini.util.ts` `cleanupParameters` (@ ac0fafec) — an allowlist |
| 79 | + (`type, format, title, description, nullable, enum, maxItems, minItems, properties, required, |
| 80 | + minProperties, maxProperties, minLength, maxLength, pattern, example, anyOf, propertyOrdering, |
| 81 | + default, items, minimum, maximum`) that deletes everything else, so **`prefixItems` is silently |
| 82 | + dropped and no `items` is synthesized** — a tuple array becomes a bare `{"type":"array"}`. |
| 83 | + |
| 84 | +## Takeaway for a Gemini bridge |
| 85 | + |
| 86 | +Only one reference (opencode's Moonshot path) derives `items` from `prefixItems`. The pragmatic, |
| 87 | +production-proven behavior for Gemini/Antigravity is CLIProxyAPI's: if `type` includes `array` and |
| 88 | +`items` is absent, inject `{"type":"string"}` — and, unlike CLIProxyAPI, also drop or fold |
| 89 | +`prefixItems` since Gemini's schema dialect does not define it. |
0 commit comments