We run a document extraction pipeline on Gemini with a native responseSchema attached, not a "please reply with JSON" instruction in the prompt text. Over two months, three separate production problems traced back to behaviours of that schema that are not in Google's documentation.
These are the rules we ship with now, and the measurement behind each one. The domain is anonymized (no client, no industry, role codes renamed). Every number, date, model name and error string is real.
TL;DR
Order the required array identity, then evidence, then derived. It controls emission order, and emission order controls correctness.
Count your total enum values before shipping. There is an undocumented ceiling and it is lower than you think.
