JSON Schema Support

JSON Schemas are used in two places in this library:

Tool parameter schemas — the parameters field on tool definitions
Response schemas — the response_schema field on ChatCompletionRequest for structured JSON output

Each provider supports a different subset of JSON Schema, and the library automatically sanitizes schemas for Google compatibility where possible.

Cross-Provider Compatibility#

The following JSON Schema features work across all providers (OpenAI, Anthropic, Google, Alibaba):

Feature	Example
`type`	`"type": "string"`
`properties`	`"properties": {"name": {"type": "string"}}`
`required`	`"required": ["name"]`
`description`	`"description": "The user's name"`
`enum` (strings)	`"enum": ["celsius", "fahrenheit"]`
`items` (arrays)	`"items": {"type": "string"}`
`anyOf`	`"anyOf": [{"type": "string"}, {"type": "integer"}]`
`default`	`"default": "celsius"`

Google Schema Sanitization#

Google Gemini does not support several JSON Schema features that OpenAI, Anthropic, and Alibaba accept. The library automatically handles these when using the Google provider:

Feature	Behavior
`additionalProperties: false`	Silently stripped
`additionalProperties: true`	Raises `InvalidToolError`
`const`	Converted to single-value `enum`
`allOf`	Raises `InvalidToolError`
`["string", "null"]` union types	Converted to `"type": "string", "nullable": true`
Non-string `enum` values	Raises `InvalidToolError`

For schemas that raise InvalidToolError, you'll need to restructure them for Google compatibility. For example, instead of additionalProperties: true, consider using an array of key-value objects:

# Instead of this (not supported on Google):
"metadata": {
    "type": "object",
    "additionalProperties": True
}

# Use this:
"metadata": {
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "key": {"type": "string"},
            "value": {"type": "string"}
        },
        "required": ["key", "value"]
    }
}

Provider-Specific Differences#

Feature	OpenAI	Anthropic	Google	Alibaba
`additionalProperties`	Required `false` in strict mode	Required `false` in strict mode	Not supported	Same as OpenAI
`minimum` / `maximum`	Not supported	SDK moves to description	Supported	Not supported
`minLength` / `maxLength`	Not supported	SDK moves to description	Supported	Not supported
`pattern`	Not supported	Supported	Supported	Not supported
`format`	Not supported	Supported	Supported	Not supported
`const`	Supported	Supported	Auto-converted to `enum`	Supported
`allOf`	Not documented	Supported	Not supported	Not documented
`nullable: true`	Use `["type", "null"]`	Use `["type", "null"]`	Supported (Google-specific)	Use `["type", "null"]`
Non-string `enum`	Supported	Supported	Not supported	Supported
Recursive schemas	Supported	Not supported	Limited	Supported

Recommendations#

For maximum portability across providers, stick to:

Basic types: string, number, integer, boolean, object, array
properties, required, description, enum (strings only), items
Avoid additionalProperties, const, allOf, pattern, format, minimum/maximum