How to Use the Gemini Structured Output Schema Prompt to Get JSON That Parses on the First Try

Extraction jobs fail in boring ways: a date in the wrong format, a limit the model guessed because the scan was cut off, a category that does not exist in your database. Gemini's structured output feature helps by constraining responses to a schema, but the schema has to be designed for the subset Gemini accepts and for the documents you actually have. The Gemini API Structured Output Schema Builder: response_mime_type JSON, response_schema from Pydantic, Enums, propertyOrdering, Nullable Fields, and Validation Retries prompt designs that schema, writes the google-genai config, and adds a validation and retry plan so bad responses go to review instead of your database.

What the prompt produces

1. A schema design table with type, enum values, nullable, required, and a description that tells the model how to fill each field.
2. A Pydantic model (or a TypeScript type for the JS SDK) mapped to your downstream table.
3. The request config with response_mime_type set to application/json and response_schema set to your model, plus a system instruction.
4. Field ordering that puts evidence fields before answers.
5. Null and enum rules so the model returns null or "other" instead of guessing.
6. A test plan with expected JSON for each sample, including a messy one.
7. Validation and retry steps and what to log.
8. A cost and size note on descriptions, list lengths, and nesting.

How to fill the inputs

ExtractionTask describes what goes in and what comes out: document type, length, language, and the job.

FieldList is the heart of the prompt. For each field give the type, allowed values, whether it is required, and an example value. If a value can be missing on real documents, say so here.

ModelAndSDK names the Gemini model, SDK, and whether you use the Gemini Developer API or Vertex AI. Parameter names and supported schema features can differ between versions, so the prompt marks anything uncertain for you to confirm in the current docs.

SampleDocs should include at least one bad document: a cut off scan, a handwritten field, or a missing page.

Downstream tells the prompt where the JSON goes, so types match your table.

Reading the example output

The example pulls policies from insurance certificates. The schema puts a source_quote field first, so the model copies the line it read before writing a limit. The policy type is an enum with an "other" value. The occurrence limit is a nullable integer, and the system instruction says to use null when a value is cut off.

The config passes the Pydantic model directly as response_schema. The test plan expects a null limit and a partial quote for the umbrella policy on the cut off scan, never a guessed number. If validation fails, the code retries once with the error message and then routes the document to a review queue.

Tips for better results

• Write field descriptions as instructions, such as "YYYY-MM-DD" or "copy exactly as printed".
• Prefer flat schemas. Deep nesting makes responses harder to validate and debug.
• Cap list lengths so a confused response cannot produce hundreds of rows.
• Keep a small set of tricky documents as a regression test and rerun it whenever you change the schema or model.

Mistakes to avoid

• Do not make every field required with no null option. That pushes the model to invent values.
• Do not rely on schema keywords Gemini may not support. The prompt replaces them with simpler patterns and flags them.
• Do not skip your own validation. Structured output reduces errors but does not replace checks.

Who it is for

Developers and data engineers building document extraction, classification, or form parsing on the Gemini API, and teams moving an extraction pipeline from another provider to Gemini.

A practical routine

Start with five real documents, run the prompt, and paste the generated code into a notebook. Compare output to the expected JSON from the test plan, tighten descriptions where it drifts, and only then wire it into your pipeline with logging on every retry.

Related PromptDig links

Open the Gemini API Structured Output Schema Builder: response_mime_type JSON, response_schema from Pydantic, Enums, propertyOrdering, Nullable Fields, and Validation Retries prompt with your field list and sample documents. For more AI tool prompts, Browse more prompts. If you have a schema pattern that works well, Share a prompt.