Please document allowed schema complexity

Gemini API
,
1

In the Limitations section of Strucuted Outputs, it is mentioned:

Schema complexity: The API may reject very large or deeply nested schemas. If you encounter errors, try simplifying your schema by shortening property names, reducing nesting, or limiting the number of constraints.

But this is too vague and leads to a lot of trial and error experiment in designing schema that Gemini will accept. I’m not sure if this is an API issue or model issue because:

  1. Other models OpenAI’s and Grok work the same schema without any issue.
  2. Running Gemma locally with llamacpp respects the schema properly.
  3. The issue is persistent in both Gemini and Gemma provided by Gemini API.

Either way, documenting or providing a sample schema as as a threshold will make it easier for one to develop schemas. Please provide a sample schema or elaborate what exactly will make Gemini API throw out complexity issue.

3

Hi @Arun_Mani,

Welcome to the Google AI Forum! :confetti_ball: :confetti_ball:

Thanks for reporting this issue and we value your feedback. I will report this issue to docs team.. Can you please share some examples that are working with Open AI and Grok but not with Gemini API..

1 Like
5

Hello, thanks for offering to help!

Here is a script with schema that throws the error.

import requests
import json

API_KEY = "XYZ"
API_URL = "https://generativelanguage.googleapis.com/v1beta/openai/v1/chat/completions"
MODEL = "gemini-2.5-flash"

schema = {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "User Profiles List",
    "type": "object",
    "properties": {
        "profiles": {
            "type": "array",
            "maxItems": 3,
            "items": {
                "type": "object",
                "properties": {
                    "id": {"type": "integer", "minimum": 1},
                    "name": {"type": "string", "minLength": 1},
                    "email": {"type": "string", "format": "email"},
                    "address": {
                        "type": "object",
                        "properties": {
                            "street": {"type": "string"},
                            "city": {"type": "string"},
                            "country": {"type": "string", "default": "USA"},
                            "coordinates": {
                                "type": "object",
                                "properties": {
                                    "latitude": {
                                        "type": "number",
                                        "minimum": -90,
                                        "maximum": 90,
                                    },
                                    "longitude": {
                                        "type": "number",
                                        "minimum": -180,
                                        "maximum": 180,
                                    },
                                },
                                "required": ["latitude", "longitude"],
                            },
                        },
                        "required": ["street", "city", "coordinates"],
                    },
                    "preferences": {
                        "type": "object",
                        "properties": {
                            "theme": {
                                "type": "string",
                                "enum": ["light", "dark", "auto"],
                            },
                            "notifications": {
                                "type": "object",
                                "properties": {
                                    "email": {"type": "boolean"},
                                    "push": {"type": "boolean"},
                                    "sms": {"type": "boolean"},
                                },
                                "required": ["email", "push"],
                            },
                        },
                        "required": ["theme", "notifications"],
                    },
                },
                "required": ["id", "name", "email", "address", "preferences"],
            },
        }
    },
    "required": ["profiles"],
}

payload = {
    "model": MODEL,
    "messages": [
        {"role": "user", "content": "Generate a list of 1 to 3 user profiles."}
    ],
    "response_format": {
        "type": "json_schema",
        "json_schema": {"name": "user_profiles_list", "strict": True, "schema": schema},
    },
}

headers = {"Content-Type": "application/json", "Authorization": f"Bearer {API_KEY}"}

response = requests.post(API_URL, headers=headers, json=payload)
data = response.json()
print("RAW DATA", data)
json_output = data["choices"][0]["message"]["content"]

print(json.dumps(json.loads(json_output), indent=2))

And on running:

RAW DATA [{'error': {'code': 400, 'message': 'A schema in GenerationConfig in the request exceeds the maximum allowed nesting depth.', 'status': 'INVALID_ARGUMENT'}}]
Traceback (most recent call last):
  File "/x/y/z/test_json.py", line 90, in <module>
    json_output = data["choices"][0]["message"]["content"]
                  ~~~~^^^^^^^^^^^
TypeError: list indices must be integers or slices, not str