Gemini API: Resolving `additionalProperties` Schema Rejection

The Gemini API, since its November 2025 update, officially supports the additionalProperties keyword in JSON schemas for structured outputs. This enhancement, as highlighted in Google's official blog post and documentation, allows for more flexible and robust schema definitions. However, a persistent issue arises within the google-genai SDK, where client-side validation in _transformers.py incorrectly rejects schemas containing additionalProperties. This discrepancy hinders developers from fully leveraging the API's capabilities and necessitates workarounds to implement desired functionalities.

Understanding the Problem

The core of the issue lies in the SDK's validation process. The process_schema() function within the SDK applies a stricter validation subset than what the Gemini API actually supports. This overly restrictive validation inadvertently blocks valid schemas that include the additionalProperties keyword. This keyword is essential for defining schemas that allow for additional, unspecified properties, providing flexibility in data structures. The rejection manifests as a 400 INVALID_ARGUMENT error, specifically indicating an "Unknown name "additional_properties"" within the schema.

To illustrate this problem, consider the provided code snippet:

from google import genai
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    value: int

    class Config:
        extra = "forbid"  # Generates additionalProperties: false in JSON schema

client = genai.Client(api_key="...")
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Generate an item",
    config={
        "response_mime_type": "application/json",
        "response_schema": Item,
    },
)

In this example, the Item class is defined using Pydantic, with the extra = "forbid" configuration generating additionalProperties: false in the JSON schema. While the Gemini API should accept this schema, the SDK's validation process flags it as invalid, leading to the aforementioned error. This behavior directly contradicts the announced support for additionalProperties and the documented functionality of the Gemini API.

The implications of this issue extend beyond a simple validation error. Developers are forced to either abandon the use of additionalProperties or resort to workarounds, such as using response_json_schema instead of response_schema. This workaround, while functional, bypasses the SDK's validation and requires manual schema handling, negating the ergonomic benefits of Pydantic integration. This added complexity increases development time and effort, hindering the efficient utilization of the Gemini API.

Analyzing the Root Cause

To effectively address this issue, it is crucial to delve into the underlying reasons for the SDK's behavior. The discrepancy between the SDK's validation rules and the API's supported features suggests a potential lag in SDK updates. While the Gemini API evolved to incorporate additionalProperties, the SDK's validation logic might not have been updated accordingly. This lag can stem from various factors, including versioning inconsistencies, delayed synchronization between API and SDK development cycles, or unforeseen complexities in implementing the updated validation rules.

Another potential contributing factor could be the SDK's design philosophy regarding schema validation. The SDK might be intentionally employing a more restrictive validation approach to enforce stricter data contracts and prevent potential runtime errors. While such a conservative approach can enhance robustness, it can also inadvertently limit the flexibility offered by the API. In the case of additionalProperties, the SDK's stringent validation might be overriding the API's intended behavior, thus creating the observed conflict.

Furthermore, the interaction between Pydantic and the SDK's schema processing could be a source of the problem. Pydantic, a popular Python library for data validation and serialization, automatically generates JSON schemas based on class definitions. The SDK's process_schema() function then processes these Pydantic-generated schemas. It is conceivable that the interaction between these two components is not fully optimized for handling additionalProperties, leading to the observed validation errors. Investigating the specific steps involved in schema processing and identifying any potential bottlenecks or misinterpretations is essential for resolving this aspect of the issue.

Proposed Solutions and Workarounds

Addressing the additionalProperties rejection issue requires a multifaceted approach, encompassing both immediate workarounds and long-term solutions. For developers currently facing this problem, the primary workaround involves utilizing the response_json_schema parameter instead of response_schema. This approach bypasses the SDK's internal validation, allowing schemas with additionalProperties to be passed directly to the Gemini API. However, as previously mentioned, this workaround necessitates manual schema handling and sacrifices the convenience of Pydantic integration. Therefore, it should be considered a temporary measure until a more comprehensive solution is implemented.

In the long term, the most effective solution lies in updating the google-genai SDK to align its validation logic with the Gemini API's capabilities. This update should involve modifying the process_schema() function to correctly handle schemas containing additionalProperties, ensuring that valid schemas are not erroneously rejected. The SDK developers should prioritize this update to restore consistency between the SDK and the API, enabling developers to seamlessly leverage the full functionality of the Gemini API.

In addition to updating the SDK's validation logic, improving the integration between Pydantic and the SDK's schema processing is crucial. This improvement might involve revising the way Pydantic-generated schemas are handled within the SDK, ensuring that additionalProperties is correctly interpreted and processed. Collaborating with the Pydantic community to identify and address any potential compatibility issues could further enhance this integration.

Furthermore, providing clear and comprehensive documentation regarding the use of additionalProperties within the Gemini API and the SDK is essential. This documentation should outline the supported schema formats, best practices for defining schemas with additionalProperties, and any known limitations or workarounds. By empowering developers with the necessary information, the likelihood of encountering and resolving issues related to additionalProperties can be significantly reduced.

Impact and Implications

The incorrect rejection of schemas with additionalProperties has significant implications for developers utilizing the Gemini API. It restricts the flexibility in defining data structures, hindering the creation of robust and adaptable applications. Developers are forced to either compromise on their schema design or implement cumbersome workarounds, leading to increased development time and effort. This issue also undermines the value proposition of the Gemini API's structured output capabilities, as developers cannot fully exploit the API's schema support.

Moreover, the discrepancy between the SDK's validation and the API's functionality creates confusion and frustration among developers. The unexpected rejection of valid schemas can lead to time-consuming debugging efforts and hinder the overall developer experience. Maintaining consistency between the SDK and the API is crucial for fostering trust and confidence in the platform. Addressing the additionalProperties issue is therefore paramount for ensuring a smooth and productive developer workflow.

The impact extends beyond individual developers to the broader ecosystem surrounding the Gemini API. If developers perceive the platform as inconsistent or unreliable, they might be less inclined to adopt it for their projects. This can stifle innovation and limit the API's potential reach. Conversely, resolving this issue and demonstrating a commitment to developer experience can enhance the platform's reputation and attract a wider audience.

Conclusion

The issue of the google-genai SDK rejecting schemas with additionalProperties despite the Gemini API's support is a critical problem that needs to be addressed. While workarounds exist, the long-term solution lies in updating the SDK's validation logic and improving its integration with Pydantic. By resolving this issue, the Gemini API can deliver on its promise of flexible and robust structured outputs, empowering developers to build innovative applications. Google's commitment to addressing this issue will not only improve the developer experience but also strengthen the Gemini API's position as a leading platform for AI-powered applications.

For more information on JSON Schema and additionalProperties, you can visit the official JSON Schema website.