Support enhanced JSON Schema features in Google Gemini 2.5+ models

conradlee · claude · conradlee · commit f5911d3534ca · 2025-11-06T16:50:35.000+01:00
Google announced in November 2025 that Gemini 2.5+ models now support enhanced JSON Schema features including title, $ref/$defs, anyOf/oneOf, minimum/maximum, additionalProperties, prefixItems, and property ordering. This removes workarounds in GoogleJsonSchemaTransformer and allows native $ref and oneOf support instead of forced inlining and conversion. Key findings from empirical testing: - Native $ref/$defs support confirmed (no inlining needed) - Both anyOf and oneOf work natively (no conversion needed) - exclusiveMinimum/exclusiveMaximum NOT yet supported by Google SDK Changes: - Set prefer_inlined_defs=False to use native $ref/$defs instead of inlining - Remove oneOf→anyOf conversion (both work natively now) - Remove adapter code that stripped title, additionalProperties, and prefixItems - Keep stripping exclusiveMinimum/exclusiveMaximum (not yet supported) - Remove code that raised errors for $ref schemas - Update GoogleJsonSchemaTransformer docstring to document all supported features - Update test_json_def_recursive to verify recursive schemas work with $ref - Add comprehensive test suite for new JSON Schema capabilities - Add documentation section highlighting enhanced JSON Schema support with examples 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/docs/models/google.md b/docs/models/google.md
@@ -201,6 +201,70 @@ agent = Agent(model)
 
 `GoogleModel` supports multi-modal input, including documents, images, audio, and video. See the [input documentation](../input.md) for details and examples.
 
+## Enhanced JSON Schema Support
+
+As of November 2025, Google Gemini models (2.5+) provide enhanced support for JSON Schema features when using [`NativeOutput`](../output.md#native-output), enabling more sophisticated structured outputs:
+
+### Supported Features
+
+- **Property Ordering**: The order of properties in your Pydantic model definition is now preserved in the output
+- **Title Fields**: The `title` field is supported for providing short property descriptions
+- **Union Types (`anyOf` and `oneOf`)**: Full support for conditional structures using Python's `Union` or `|` type syntax
+- **Recursive Schemas (`$ref` and `$defs`)**: Full support for self-referential models and reusable schema definitions, enabling tree structures and recursive data
+- **Numeric Constraints**: `minimum` and `maximum` constraints are respected (note: `exclusiveMinimum` and `exclusiveMaximum` are not yet supported)
+- **Optional Fields (`type: 'null'`)**: Proper handling of optional fields with `None` values
+- **Additional Properties**: Dictionary fields with `dict[str, T]` are fully supported
+- **Tuple Types (`prefixItems`)**: Support for tuple-like array structures
+
+### Example: Recursive Schema
+
+```python
+from pydantic import BaseModel
+from pydantic_ai import Agent
+from pydantic_ai.models.google import GoogleModel
+from pydantic_ai.output import NativeOutput
+
+class TreeNode(BaseModel):
+    """A tree node that can contain child nodes."""
+    value: int
+    children: list['TreeNode'] | None = None
+
+model = GoogleModel('gemini-2.5-pro')
+agent = Agent(model, output_type=NativeOutput(TreeNode))
+
+result = await agent.run('Create a tree with root value 1 and two children with values 2 and 3')
+# result.output will be a TreeNode with proper structure
+```
+
+### Example: Union Types
+
+```python
+from typing import Union, Literal
+from pydantic import BaseModel
+from pydantic_ai import Agent
+from pydantic_ai.models.google import GoogleModel
+from pydantic_ai.output import NativeOutput
+
+class Success(BaseModel):
+    status: Literal['success']
+    data: str
+
+class Error(BaseModel):
+    status: Literal['error']
+    error_message: str
+
+class Response(BaseModel):
+    result: Union[Success, Error]
+
+model = GoogleModel('gemini-2.5-pro')
+agent = Agent(model, output_type=NativeOutput(Response))
+
+result = await agent.run('Process this request successfully')
+# result.output.result will be either Success or Error
+```
+
+See the [structured output documentation](../output.md) for more details on using `NativeOutput` with Pydantic models.
+
 ## Model settings
 
 You can customize model behavior using [`GoogleModelSettings`][pydantic_ai.models.google.GoogleModelSettings]:
diff --git a/pydantic_ai_slim/pydantic_ai/profiles/google.py b/pydantic_ai_slim/pydantic_ai/profiles/google.py
@@ -1,9 +1,5 @@
 from __future__ import annotations as _annotations
 
-import warnings
-
-from pydantic_ai.exceptions import UserError
-
 from .._json_schema import JsonSchema, JsonSchemaTransformer
 from . import ModelProfile
 
@@ -23,84 +19,55 @@ def google_model_profile(model_name: str) -> ModelProfile | None:
 class GoogleJsonSchemaTransformer(JsonSchemaTransformer):
     """Transforms the JSON Schema from Pydantic to be suitable for Gemini.
 
-    Gemini which [supports](https://ai.google.dev/gemini-api/docs/function-calling#function_declarations)
-    a subset of OpenAPI v3.0.3.
+    Gemini supports [a subset of OpenAPI v3.0.3](https://ai.google.dev/gemini-api/docs/function-calling#function_declarations).
+
+    As of November 2025, Gemini 2.5+ models support enhanced JSON Schema features including:
+    * `title` for short property descriptions
+    * `anyOf` and `oneOf` for conditional structures (unions)
+    * `$ref` and `$defs` for recursive schemas and reusable definitions
+    * `minimum` and `maximum` for numeric constraints
+    * `additionalProperties` for dictionaries
+    * `type: 'null'` for optional fields
+    * `prefixItems` for tuple-like arrays
 
-    Specifically:
-    * gemini doesn't allow the `title` keyword to be set
-    * gemini doesn't allow `$defs` — we need to inline the definitions where possible
+    Note: `exclusiveMinimum` and `exclusiveMaximum` are not yet supported by the Google SDK.
     """
 
     def __init__(self, schema: JsonSchema, *, strict: bool | None = None):
-        super().__init__(schema, strict=strict, prefer_inlined_defs=True, simplify_nullable_unions=True)
+        super().__init__(schema, strict=strict, prefer_inlined_defs=False, simplify_nullable_unions=True)
 
     def transform(self, schema: JsonSchema) -> JsonSchema:
-        # Note: we need to remove `additionalProperties: False` since it is currently mishandled by Gemini
-        additional_properties = schema.pop(
-            'additionalProperties', None
-        )  # don't pop yet so it's included in the warning
-        if additional_properties:
-            original_schema = {**schema, 'additionalProperties': additional_properties}
-            warnings.warn(
-                '`additionalProperties` is not supported by Gemini; it will be removed from the tool JSON schema.'
-                f' Full schema: {self.schema}\n\n'
-                f'Source of additionalProperties within the full schema: {original_schema}\n\n'
-                'If this came from a field with a type like `dict[str, MyType]`, that field will always be empty.\n\n'
-                "If Google's APIs are updated to support this properly, please create an issue on the Pydantic AI GitHub"
-                ' and we will fix this behavior.',
-                UserWarning,
-            )
-
-        schema.pop('title', None)
+        # Remove properties not supported by Gemini
         schema.pop('$schema', None)
         if (const := schema.pop('const', None)) is not None:
             # Gemini doesn't support const, but it does support enum with a single value
             schema['enum'] = [const]
         schema.pop('discriminator', None)
         schema.pop('examples', None)
 
-        # TODO: Should we use the trick from pydantic_ai.models.openai._OpenAIJsonSchema
-        #   where we add notes about these properties to the field description?
-        schema.pop('exclusiveMaximum', None)
-        schema.pop('exclusiveMinimum', None)
-
         # Gemini only supports string enums, so we need to convert any enum values to strings.
         # Pydantic will take care of transforming the transformed string values to the correct type.
         if enum := schema.get('enum'):
             schema['type'] = 'string'
             schema['enum'] = [str(val) for val in enum]
 
         type_ = schema.get('type')
-        if 'oneOf' in schema and 'type' not in schema:  # pragma: no cover
-            # This gets hit when we have a discriminated union
-            # Gemini returns an API error in this case even though it says in its error message it shouldn't...
-            # Changing the oneOf to an anyOf prevents the API error and I think is functionally equivalent
-            schema['anyOf'] = schema.pop('oneOf')
-
         if type_ == 'string' and (fmt := schema.pop('format', None)):
             description = schema.get('description')
             if description:
                 schema['description'] = f'{description} (format: {fmt})'
             else:
                 schema['description'] = f'Format: {fmt}'
 
-        if '$ref' in schema:
-            raise UserError(f'Recursive `$ref`s in JSON Schema are not supported by Gemini: {schema["$ref"]}')
+        # As of November 2025, Gemini 2.5+ models now support:
+        # - additionalProperties (for dict types)
+        # - $ref (for recursive schemas)
+        # - prefixItems (for tuple-like arrays)
+        # These are no longer stripped from the schema.
 
-        if 'prefixItems' in schema:
-            # prefixItems is not currently supported in Gemini, so we convert it to items for best compatibility
-            prefix_items = schema.pop('prefixItems')
-            items = schema.get('items')
-            unique_items = [items] if items is not None else []
-            for item in prefix_items:
-                if item not in unique_items:
-                    unique_items.append(item)
-            if len(unique_items) > 1:  # pragma: no cover
-                schema['items'] = {'anyOf': unique_items}
-            elif len(unique_items) == 1:  # pragma: no branch
-                schema['items'] = unique_items[0]
-            schema.setdefault('minItems', len(prefix_items))
-            if items is None:  # pragma: no branch
-                schema.setdefault('maxItems', len(prefix_items))
+        # Note: exclusiveMinimum/exclusiveMaximum are NOT yet supported by Google SDK,
+        # so we still need to strip them
+        schema.pop('exclusiveMinimum', None)
+        schema.pop('exclusiveMaximum', None)
 
         return schema
diff --git a/tests/models/test_gemini.py b/tests/models/test_gemini.py
@@ -445,6 +445,8 @@ class Locations(BaseModel):
 
 
 async def test_json_def_recursive(allow_model_requests: None):
+    """Test that recursive schemas with $ref are now supported (as of November 2025)."""
+
     class Location(BaseModel):
         lat: float
         lng: float
@@ -479,15 +481,18 @@ class Location(BaseModel):
         description='This is the tool for the final Result',
         parameters_json_schema=json_schema,
     )
-    with pytest.raises(UserError, match=r'Recursive `\$ref`s in JSON Schema are not supported by Gemini'):
-        mrp = ModelRequestParameters(
-            function_tools=[],
-            allow_text_output=True,
-            output_tools=[output_tool],
-            output_mode='text',
-            output_object=None,
-        )
-        mrp = m.customize_request_parameters(mrp)
+    # As of November 2025, Gemini 2.5+ models support recursive $ref in JSON Schema
+    # This should no longer raise an error
+    mrp = ModelRequestParameters(
+        function_tools=[],
+        allow_text_output=True,
+        output_tools=[output_tool],
+        output_mode='text',
+        output_object=None,
+    )
+    mrp = m.customize_request_parameters(mrp)
+    # Verify the schema still contains $ref after customization
+    assert '$ref' in mrp.output_tools[0].parameters_json_schema
 
 
 async def test_json_def_date(allow_model_requests: None):
diff --git a/tests/models/test_google_json_schema_features.py b/tests/models/test_google_json_schema_features.py
