When responseSchema Can't Do $ref: Handling Recursive Schemas in Production with responseJsonSchema

Declare a recursive category tree with a self-referencing $ref

Now the main event: recursion. A category node holds a label plus an array of child nodes, and each child is itself a CategoryNode. You write that self-reference with $ref.

tree_schema = {
    "type": "object",
    "$defs": {
        "LocalizedText": {
            "type": "object",
            "properties": {
                "ja": {"type": "string"},
                "en": {"type": "string"},
            },
            "required": ["ja", "en"],
        },
        "CategoryNode": {
            "type": "object",
            "properties": {
                "label": {"$ref": "#/$defs/LocalizedText"},
                # Each child is a CategoryNode itself -- this is the recursion
                "children": {
                    "type": "array",
                    "items": {"$ref": "#/$defs/CategoryNode"},
                },
            },
            "required": ["label", "children"],
        },
    },
    "properties": {"root": {"$ref": "#/$defs/CategoryNode"}},
    "required": ["root"],
}
 
resp = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Build a wallpaper category tree up to three levels, like Nature -> Mountain -> Snowy Mountain.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_json_schema=tree_schema,
    ),
)

The key point is that the schema doesn't hard-code the depth. When I want three levels, I ask for them in the prompt, but the schema itself permits any depth. If the real data turns out deeper or shallower, I don't rewrite the schema. With the fixed-depth inline approach, a tree deeper than expected had its leaves quietly chopped off.

Since the depth is variable, walking the returned tree recursively is the natural fit.

import json
 
def walk(node, depth=0):
    label = node["label"]["ja"]
    print("  " * depth + f"- {label}")
    for child in node.get("children", []):
        walk(child, depth + 1)
 
data = json.loads(resp.text)
walk(data["root"])
 
# Example output:
# - 自然
#   - 山
#     - 雪山

Being able to pin the tree shape in the schema keeps downstream processing simple. For column design when writing results to Sheets, and for the field-order drift that can break that, pair this with what I covered in pinning field order with propertyOrdering.

Validate to guarantee the shape

Structured output doesn't mean "I passed a schema, so it's always the right shape." Before anything reaches production ingestion, I always run local JSON Schema validation. The nice part is that the schema you hand to responseJsonSchema is ordinary JSON Schema, so you can revalidate it with the jsonschema library as-is.

import json
from jsonschema import Draft202012Validator, ValidationError
 
def parse_validated(resp_text: str, schema: dict) -> dict:
    data = json.loads(resp_text)
    validator = Draft202012Validator(schema)
    errors = sorted(validator.iter_errors(data), key=lambda e: e.path)
    if errors:
        # Surface just the first error concretely, for retry decisions
        first = errors[0]
        path = "/".join(str(p) for p in first.path) or "(root)"
        raise ValidationError(f"{path}: {first.message}")
    return data
 
# Reuse the exact same schema you passed to the API
data = parse_validated(resp.text, tree_schema)

The quietly valuable part is that the schema passed to the API and the schema used for validation are the same object. The OpenAPI subset behind responseSchema can't be fed straight into jsonschema, so you had to maintain a separate validation schema or run a conversion. After migrating, that double bookkeeping disappears. For running validation and suppressed retries while measuring them, I wrote up the details in an operations note on structured output silently drifting off schema.

Common mistakes and traps

Here are the ones I actually hit mid-migration.

Setting responseSchema and responseJsonSchema together. These two are exclusive. Passing both to GenerateContentConfig errors out. When migrating, be sure to remove the old response_schema. I forgot to comment it out at first, got a 400, and spent a while chasing the cause.

Trying to bring propertyOrdering along. propertyOrdering is a responseSchema concept; responseJsonSchema has no equivalent. If you have a hard requirement to control field order strictly, that's the one point where responseSchema still has the edge. For tasks where order is essential, not migrating is a legitimate choice.

Assuming every JSON Schema keyword works. $ref/$defs are handled, but not every JSON Schema keyword (complex conditionals, some format constraints) is guaranteed to take effect. Check the supported keywords in the official docs, and don't offload elaborate constraints entirely to the schema; back them with downstream validation. I split the roles as "schema for the skeleton, jsonschema for the fine constraints."

Asking a low-effort model for a deep tree. A deeply recursive schema is a demanding generation. Ask an extremely shallow-reasoning configuration for a deep tree and it may cut children off partway. When deep structure matters, choosing a model with reasoning headroom was more stable. For switching types by input kind itself, my operations note on anyOf discriminated unions is a useful reference.

How to choose between them

My rule is simple. Reach for responseJsonSchema when you need shared-definition reuse or recursion; reach for responseSchema when you need strict field-order pinning. For flat structures needing neither, use whichever you're comfortable with. For a case like mine, multilingual and nested data in indie development, the payoff from centralizing definitions with $defs was large, and migrating was the right call.

One caveat: the support status described here is accurate as of writing. Gemini's API moves fast, so before you build, confirm the supported keywords and per-model availability in the official docs once. Start by carving your deepest schema out into $defs, moving it onto responseJsonSchema, and getting a single call through. The relief of watching the inline duplication vanish is what will carry the rest of the migration.

Thanks for reading.