Support enhanced JSON Schema features in Google Gemini 2.5+ models

[conradlee]

Summary

Updates GoogleJsonSchemaTransformer to support enhanced JSON Schema features announced by Google in November 2025 for Gemini 2.5+ models.

Transformer Changes (Before → After)

Before: 90+ lines with extensive workarounds
After: ~47 lines with minimal transformations

Removed Workarounds (Now Natively Supported)

• ❌ Enum-to-string conversion → ✅ Native typed enums (integer, string, etc.)
• ❌ additionalProperties warning/removal → ✅ Native dict support
• ❌ title field removal → ✅ Preserved
• ❌ oneOf → anyOf conversion → ✅ Both work natively
• ❌ $ref recursion errors → ✅ Native $ref/$defs support
• ❌ prefixItems → items conversion → ✅ Native tuple support
• ❌ prefer_inlined_defs=True → ✅ Native $defs with references
• ❌ simplify_nullable_unions=True → ✅ Native type: 'null'

Still Transformed (Not Yet Supported)

• $schema, const, discriminator, examples → Removed
• format (date, time, etc.) → Moved to description field
• exclusiveMinimum/exclusiveMaximum → Removed

New Capabilities

• Recursive schemas: Tree structures, linked lists, nested graphs
• Discriminated unions: Type-safe union types with discriminator fields
• Typed enums: Integer/string enums without conversion
• Complex dictionaries: dict[str, ComplexType] with schema validation
• Optional fields: Native type: 'null' support

Tests

Added 6 comprehensive tests in test_google.py:

• Discriminated unions with oneOf
• Recursive schemas with $ref/$defs
• Dicts with additionalProperties
• Optional/nullable fields
• Integer enums

Updated 7 snapshot tests in test_gemini.py to reflect new native behavior.

Migration Impact

Fully backwards-compatible - existing code continues to work, schemas are now more expressive.

---

🤖 Generated with Claude Code

Related: Google Announcement - Gemini API Structured Outputs

Fixes #3364

[DouweM]

Are you sure? https://blog.google/technology/developers/gemini-api-structured-outputs/ and https://ai.google.dev/gemini-api/docs/structured-output are about the Gemini API, not Vertex.

[DouweM]

Note that https://ai.google.dev/gemini-api/docs/structured-output?example=feedback#model_support says we have to use response_json_schema instead of the response_schema key we currently set:

pydantic-ai/pydantic_ai_slim/pydantic_ai/models/google.py

Line 458 in 4cc4f35

response_schema=response_schema,

pydantic-ai/pydantic_ai_slim/pydantic_ai/models/google.py

Line 294 in 4cc4f35

response_schema=generation_config.get('response_schema'),

When we do that, maybe it will work for GLA and Vertex?

[conradlee]

You're right, I've updated the PR. Tests show there's not a difference (with one possible exception -- see the comment below)

[DouweM]

Instead of testing the schema transformer itself, we should add a test to test_google.py that uses a BaseModel like this as NativeOutput and then verifies that the request succeeds.

[DouweM]

@conradlee Thanks for working on this Conrad!

[conradlee]

⚠️ Recursive Schemas with gemini-2.5-flash: Testing Note

Test: test_google_recursive_schema_native_output_gemini_2_5
Status: ✅ PASSING (with Vertex AI provider)

Issue Found During Development

During development of this PR, testing recursive schemas with gemini-2.5-flash revealed different behavior between Google's two APIs:

• Vertex AI (vertex_provider): ✅ WORKS - Recursive schemas with $ref and $defs work correctly
• GLA (google_provider with GEMINI_API_KEY): ❌ FAILED - Consistently returned 500 Internal Server Error

google.genai.errors.ServerError: 500 INTERNAL.
{'error': {
    'code': 500,
    'message': 'An internal error has occurred. Please retry or report...'
}}

Current Status

The test now uses vertex_provider and passes successfully with a recorded cassette. All other enhanced JSON Schema features work with gemini-2.5-flash on both APIs:

• ✅ Discriminated unions (oneOf with discriminator)
• ✅ Dicts with additionalProperties
• ✅ Optional/nullable fields (type: 'null')
• ✅ Integer enums
• ✅ Recursive schemas on Vertex AI
• ❌ Recursive schemas on GLA (may be temporary or API-key-specific)

Action Requested

Please verify: Can someone with a GLA API key test recursive schemas with gemini-2.5-flash and confirm whether:

1. This is a temporary API issue
2. This is specific to certain API keys/projects
3. This is a known limitation of the GLA endpoint

The GLA failure may need to be reported to Google if it's reproducible.

---

I suspect that something is just off with my Gemini API Key (I actually only use vertex mode in dev and prod) and so perhaps that's the reason. @DouweM it would be great if you could modify this test to use the google provider (rather than the vertex provider) and see whether it passes for you.

[DouweM]

it would be great if you could modify this test to use the google provider (rather than the vertex provider) and see whether it passes for you.

@conradlee It's failing for me as well, I've asked our contacts at Google if that's expected or not.

[DouweM]

We don't have a test yet that verifies that prefixItems now works

[conradlee]

Now added a test for this based on a coordinate class whose json schema representation looks like

{
  "description": "A 2D coordinate with latitude and longitude.",
  "properties": {
    "point": {
      "maxItems": 2,
      "minItems": 2,
      "prefixItems": [
        {
          "type": "number"
        },
        {
          "type": "number"
        }
      ],
      "title": "Point",
      "type": "array"
    }
  },
  "required": [
    "point"
  ],
  "title": "Coordinate",
  "type": "object"
}

Luckily this test passes with the google provider.