Support Gemini enhanced JSON Schema features

[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.

[conradlee]

@DouweM I have added support for the simplify_nullable_unions kwarg and added test coverage of it as well. I added some TODO comments suggesting this code be removed in v2.

From my perspective, the only remaining issue is to clarify whether GLA supports recursive schemas.

[conradlee]

Also this script demonstrates in a bit more depth that support for recursive schemas (which is officially claimed here) is flakey: https://gist.github.com/conradlee/a884a8eee7ad78e256b51d4a688b2ad6

[DouweM]

@conradlee Thanks for doing the testing Conrad, I've shared that with Google.

For now let's continue with this PR on the assumption that we cannot rely on this working in the Gemini API, so we should keep the old inline-defs behavior (unless we can determine exactly under what conditions it does and does not work). I suggest implementing that on GoogleProvider.model_profile, where we can check self._client._api_client.vertexai. You can look at other provider model_profile methods to see how they override specific fields on the profile.

Let me know if that makes sense or if you'd like help!

[conradlee]

Hey @DouweM I brought this issue up on twitter and Philip Schmidt said the google team will look into it:
https://x.com/_philschmid/status/1989383111894053123?s=20

Interestingly, the problem is now resolved. I'm not getting the 5XX errors with recursive schemas any more--neither with the GLA nor Vertex providers. I had claude create a comprehensive test suite with different scenarios and they all passed.

Not sure why it works now and didn't before - perhaps the roll-out of the schema improvements just takes several days. In any case, the official Google docs mention that gemini supports refs, and now it really works. So I think we should use them here.

I've now added the test that uses a recursive test with the GLA provider--the is the one that was failing before but now passes. I would argue the PR is ready to merge.

[DouweM]

Not sure why it works now and didn't before - perhaps the roll-out of the schema improvements just takes several days

@conradlee Philipp confirmed to me that they fixed it in response to your/our report :)

Let me do one final review and hopefully merge...

[conradlee]

@DouweM Thanks for the prompt review. I've addressed the issues you brought up, could you have another look?

[DouweM]

We don't need the version number in this test name anymore; remember to also change the cassette

[conradlee]

I've gone a different route because there was doubt around whether this works on gemini 2.0 and 2.5. Instead I've also added tests for gemini-2.0-flash, so in this case the version number has new relevance

[DouweM]

@conradlee We're so close but I found another wrinkle: the PR title says "Gemini 2.5+", so I thought I'd check whether there's any version gating to do to keep Gemini 2.0 working, and it appears there is:

https://ai.google.dev/gemini-api/docs/structured-output?example=recipe#model_support says:

Note that Gemini 2.0 requires an explicit propertyOrdering list within the JSON input to define the preferred structure.

google-gemini/cookbook@fb674d1#diff-74f587f27880bc1ab4e63ebe4dac03066cd9826ac77282fa1101aeec9ae29825R426 says:

Important: Gemini 2.0 models require explicit ordering of keys in structured output schemas. When working with Gemini 2.0, you must define the desired property ordering as a list within the propertyOrdering field as part of your schema configuration.

So we need a test for Gemini 2.0, and I expect that in the google_model_profile function here, we need to use a slightly different JSON schema transformer for 2.0, possible a subclass that does all the same thing + set propertyOrdering (unless it turns out it's not actually required).

[conradlee]

@DouweM You're right to be sceptical of whether this will work on gemini 2.0. However I remember when I was setting the tests up some of them first pointed to gemini-2.0-flash and passed.

To that end I had a suspicion that gemini-2.0-flash supports all these features too--even if the documentation says it does not.

I have thus added versions of the tests that point to gemini-2.5-flash as well. They all pass. I think this is good news.

[DouweM]

@conradlee Thanks a lot! I'll get it out today along with Gemini 3 support (#3464) :)