🕷️ Crawler Inspector

URL Lookup

Direct Parameter Lookup

Raw Queries and Responses

1. Shard Calculation

Query:

Response:

Calculated Shard: 189 (from laksa066)

2. Crawled Status Check

Query:

curl -X POST \
  'http://laksa189.int.ahrefs:8124/' \
  -H 'Content-Type: text/plain' \
  -H 'X-ClickHouse-Database: crawler3' \
  -H 'Authorization: Basic YXBpOg==' \
  -d 'SELECT getAhrefsURLFromUnparsed(src_unparsed) AS found_url, ifNull(toUnixTimestamp(download_stamp), 0) AS crawl_time, ifNull(toUnixTimestamp(props_url_first_seen), 0) AS first_indexed_time, download_http_code AS http_code, src_unparsed AS src_unparsed, src_root_hash AS src_root_hash, history_drop_reason AS history_drop_reason, meta_title AS meta_title, meta_descriptions AS meta_descriptions, attrs_boilerpipe_text AS attrs_boilerpipe_text, attrs_markdown AS attrs_markdown, attrs_readable_markdown AS attrs_readable_markdown, meta_canonical AS meta_canonical FROM crawler3.page_info_local FINAL PREWHERE (src_root_hash, src_unparsed) IN ((getAhrefsRootHashFromUnparsed(getAhrefsUnparsedNoserviceFromURL(\'https://ai.google.dev/gemini-api/docs/structured-output\')), getAhrefsUnparsedNoserviceFromURL(\'https://ai.google.dev/gemini-api/docs/structured-output\'))) FORMAT JSONEachRow'

Response:

{"found_url":"https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output","crawl_time":1775541006,"first_indexed_time":1723669797,"http_code":200,"src_unparsed":"dev,google!ai,\/gemini-api\/docs\/structured-output s443","src_root_hash":"1013294096244278789","history_drop_reason":null,"meta_title":"Structured outputs | Gemini API | Google AI for Developers","meta_descriptions":["Learn how to generate structured JSON output with the Gemini API."],"attrs_boilerpipe_text":"Skip to main content\nGemini API\nDocs\nAPI reference\nGet API key\nCookbook\nCommunity\nGet started\nOverview\nQuickstart\nAPI keys\nLibraries\nPricing\nInteractions API\nCoding agent setup\nModels\nAll models\nGemini 3\nNano Banana\nVeo\nLyria 3\nLyria Real\nTime\nImagen\nText-to-speech\nEmbeddings\nRobotics\nCore capabilities\nText\nDocuments\nStructured outputs\nFunction calling\nLong context\nAgents\nOverview\nDeep Research Agent\nTools\nOverview\nGoogle Search\nGoogle Maps\nCode execution\nURL context\nComputer Use\nFile Search\nCombine Tools and Function calling\nLive API\nOverview\nCapabilities\nTool use\nSession management\nEphemeral tokens\nBest practices\nOptimization\nOverview\nBatch API\nFlex inference\nPriority inference\nContext caching\nGuides\nOpen\nAI compatibility\nMedia resolution\nToken counting\nPrompt engineering\nResources\nRelease notes\nDeprecations\nRate limits\nBilling info\nMigrate to Gen AI SDK\nAPI troubleshooting\nPartner and library integrations\nPolicies\nTerms of service\nAvailable regions\nAbuse monitoring\nFeedback information\nOn this page\nStreaming\nStructured outputs with tools\nJSON schema support\nType-specific properties\nModel support\nStructured outputs vs. function calling\nBest practices\nLimitations\nYou can configure Gemini models to generate responses that adhere to a provided JSON\nSchema. This ensures predictable, type-safe results and simplifies extracting\nstructured data from unstructured text.\nUsing structured outputs is ideal for:\nData extraction:\nPull specific information like names and dates from text.\nStructured classification:\nClassify text into predefined categories.\nAgentic workflows:\nGenerate structured inputs for tools or APIs.\nIn addition to supporting JSON Schema in the REST API, the Google GenAI SDKs\nmake it easy to define schemas using\nPydantic\n(Python) and\nZod\n(JavaScript).\nThis example demonstrates how to extract structured data from text using basic\nJSON Schema types like\nobject\n,\narray\n,\nstring\n, and\ninteger\n.\nfrom\ngoogle\nimport\ngenai\nfrom\npydantic\nimport\nBaseModel\n,\nField\nfrom\ntyping\nimport\nList\n,\nOptional\nclass\nIngredient\n(\nBaseModel\n):\nname\n:\nstr\n=\nField\n(\ndescription\n=\n\"Name of the ingredient.\"\n)\nquantity\n:\nstr\n=\nField\n(\ndescription\n=\n\"Quantity of the ingredient, including units.\"\n)\nclass\nRecipe\n(\nBaseModel\n):\nrecipe_name\n:\nstr\n=\nField\n(\ndescription\n=\n\"The name of the recipe.\"\n)\nprep_time_minutes\n:\nOptional\n[\nint\n]\n=\nField\n(\ndescription\n=\n\"Optional time in minutes to prepare the recipe.\"\n)\ningredients\n:\nList\n[\nIngredient\n]\ninstructions\n:\nList\n[\nstr\n]\nclient\n=\ngenai\n.\nClient\n()\nprompt\n=\n\"\"\"\nPlease extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1\/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3\/4 cup of granulated sugar,\n3\/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they'll need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes.\n\"\"\"\nresponse\n=\nclient\n.\nmodels\n.\ngenerate_content\n(\nmodel\n=\n\"gemini-3-flash-preview\"\n,\ncontents\n=\nprompt\n,\nconfig\n=\n{\n\"response_mime_type\"\n:\n\"application\/json\"\n,\n\"response_json_schema\"\n:\nRecipe\n.\nmodel_json_schema\n(),\n},\n)\nrecipe\n=\nRecipe\n.\nmodel_validate_json\n(\nresponse\n.\ntext\n)\nprint\n(\nrecipe\n)\nimport\n{\nGoogleGenAI\n}\nfrom\n\"@google\/genai\"\n;\nimport\n{\nz\n}\nfrom\n\"zod\"\n;\nimport\n{\nzodToJsonSchema\n}\nfrom\n\"zod-to-json-schema\"\n;\nconst\ningredientSchema\n=\nz\n.\nobject\n({\nname\n:\nz\n.\nstring\n().\ndescribe\n(\n\"Name of the ingredient.\"\n),\nquantity\n:\nz\n.\nstring\n().\ndescribe\n(\n\"Quantity of the ingredient, including units.\"\n),\n});\nconst\nrecipeSchema\n=\nz\n.\nobject\n({\nrecipe_name\n:\nz\n.\nstring\n().\ndescribe\n(\n\"The name of the recipe.\"\n),\nprep_time_minutes\n:\nz\n.\nnumber\n().\noptional\n().\ndescribe\n(\n\"Optional time in minutes to prepare the recipe.\"\n),\ningredients\n:\nz\n.\narray\n(\ningredientSchema\n),\ninstructions\n:\nz\n.\narray\n(\nz\n.\nstring\n()),\n});\nconst\nai\n=\nnew\nGoogleGenAI\n({});\nconst\nprompt\n=\n`\nPlease extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1\/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3\/4 cup of granulated sugar,\n3\/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they'll need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes.\n`\n;\nconst\nresponse\n=\nawait\nai\n.\nmodels\n.\ngenerateContent\n({\nmodel\n:\n\"gemini-3-flash-preview\"\n,\ncontents\n:\nprompt\n,\nconfig\n:\n{\nresponseMimeType\n:\n\"application\/json\"\n,\nresponseJsonSchema\n:\nzodToJsonSchema\n(\nrecipeSchema\n),\n},\n});\nconst\nrecipe\n=\nrecipeSchema\n.\nparse\n(\nJSON\n.\nparse\n(\nresponse\n.\ntext\n));\nconsole\n.\nlog\n(\nrecipe\n);\npackage\nmain\nimport\n(\n\"context\"\n\"fmt\"\n\"log\"\n\"google.golang.org\/genai\"\n)\nfunc\nmain\n()\n{\nctx\n:=\ncontext\n.\nBackground\n()\nclient\n,\nerr\n:=\ngenai\n.\nNewClient\n(\nctx\n,\nnil\n)\nif\nerr\n!=\nnil\n{\nlog\n.\nFatal\n(\nerr\n)\n}\nprompt\n:=\n`\nPlease extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1\/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3\/4 cup of granulated sugar,\n3\/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they'll need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes.\n`\nconfig\n:=\n&\ngenai\n.\nGenerateContentConfig\n{\nResponseMIMEType\n:\n\"application\/json\"\n,\nResponseJsonSchema\n:\nmap\n[\nstring\n]\nany\n{\n\"type\"\n:\n\"object\"\n,\n\"properties\"\n:\nmap\n[\nstring\n]\nany\n{\n\"recipe_name\"\n:\nmap\n[\nstring\n]\nany\n{\n\"type\"\n:\n\"string\"\n,\n\"description\"\n:\n\"The name of the recipe.\"\n,\n},\n\"prep_time_minutes\"\n:\nmap\n[\nstring\n]\nany\n{\n\"type\"\n:\n\"integer\"\n,\n\"description\"\n:\n\"Optional time in minutes to prepare the recipe.\"\n,\n},\n\"ingredients\"\n:\nmap\n[\nstring\n]\nany\n{\n\"type\"\n:\n\"array\"\n,\n\"items\"\n:\nmap\n[\nstring\n]\nany\n{\n\"type\"\n:\n\"object\"\n,\n\"properties\"\n:\nmap\n[\nstring\n]\nany\n{\n\"name\"\n:\nmap\n[\nstring\n]\nany\n{\n\"type\"\n:\n\"string\"\n,\n\"description\"\n:\n\"Name of the ingredient.\"\n,\n},\n\"quantity\"\n:\nmap\n[\nstring\n]\nany\n{\n\"type\"\n:\n\"string\"\n,\n\"description\"\n:\n\"Quantity of the ingredient, including units.\"\n,\n},\n},\n\"required\"\n:\n[]\nstring\n{\n\"name\"\n,\n\"quantity\"\n},\n},\n},\n\"instructions\"\n:\nmap\n[\nstring\n]\nany\n{\n\"type\"\n:\n\"array\"\n,\n\"items\"\n:\nmap\n[\nstring\n]\nany\n{\n\"type\"\n:\n\"string\"\n},\n},\n},\n\"required\"\n:\n[]\nstring\n{\n\"recipe_name\"\n,\n\"ingredients\"\n,\n\"instructions\"\n},\n},\n}\nresult\n,\nerr\n:=\nclient\n.\nModels\n.\nGenerateContent\n(\nctx\n,\n\"gemini-3-flash-preview\"\n,\ngenai\n.\nText\n(\nprompt\n),\nconfig\n,\n)\nif\nerr\n!=\nnil\n{\nlog\n.\nFatal\n(\nerr\n)\n}\nfmt\n.\nPrintln\n(\nresult\n.\nText\n())\n}\ncurl\n\"https:\/\/generativelanguage.googleapis.com\/v1beta\/models\/gemini-3-flash-preview:generateContent\"\n\\\n-H\n\"x-goog-api-key:\n$GEMINI_API_KEY\n\"\n\\\n-H\n'Content-Type: application\/json'\n\\\n-X\nPOST\n\\\n-d\n'{\n\"contents\": [{\n\"parts\":[\n{ \"text\": \"Please extract the recipe from the following text.\\nThe user wants to make delicious chocolate chip cookies.\\nThey need 2 and 1\/4 cups of all-purpose flour, 1 teaspoon of baking soda,\\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3\/4 cup of granulated sugar,\\n3\/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\\nFor the best part, they will need 2 cups of semisweet chocolate chips.\\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\\nonto ungreased baking sheets and bake for 9 to 11 minutes.\" }\n]\n}],\n\"generationConfig\": {\n\"responseMimeType\": \"application\/json\",\n\"responseJsonSchema\": {\n\"type\": \"object\",\n\"properties\": {\n\"recipe_name\": {\n\"type\": \"string\",\n\"description\": \"The name of the recipe.\"\n},\n\"prep_time_minutes\": {\n\"type\": \"integer\",\n\"description\": \"Optional time in minutes to prepare the recipe.\"\n},\n\"ingredients\": {\n\"type\": \"array\",\n\"items\": {\n\"type\": \"object\",\n\"properties\": {\n\"name\": { \"type\": \"string\", \"description\": \"Name of the ingredient.\"},\n\"quantity\": { \"type\": \"string\", \"description\": \"Quantity of the ingredient, including units.\"}\n},\n\"required\": [\"name\", \"quantity\"]\n}\n},\n\"instructions\": {\n\"type\": \"array\",\n\"items\": { \"type\": \"string\" }\n}\n},\n\"required\": [\"recipe_name\", \"ingredients\", \"instructions\"]\n}\n}\n}'\nExample Response:\n{\n\"recipe_name\"\n:\n\"Delicious Chocolate Chip Cookies\"\n,\n\"ingredients\"\n:\n[\n{\n\"name\"\n:\n\"all-purpose flour\"\n,\n\"quantity\"\n:\n\"2 and 1\/4 cups\"\n},\n{\n\"name\"\n:\n\"baking soda\"\n,\n\"quantity\"\n:\n\"1 teaspoon\"\n},\n{\n\"name\"\n:\n\"salt\"\n,\n\"quantity\"\n:\n\"1 teaspoon\"\n},\n{\n\"name\"\n:\n\"unsalted butter (softened)\"\n,\n\"quantity\"\n:\n\"1 cup\"\n},\n{\n\"name\"\n:\n\"granulated sugar\"\n,\n\"quantity\"\n:\n\"3\/4 cup\"\n},\n{\n\"name\"\n:\n\"packed brown sugar\"\n,\n\"quantity\"\n:\n\"3\/4 cup\"\n},\n{\n\"name\"\n:\n\"vanilla extract\"\n,\n\"quantity\"\n:\n\"1 teaspoon\"\n},\n{\n\"name\"\n:\n\"large eggs\"\n,\n\"quantity\"\n:\n\"2\"\n},\n{\n\"name\"\n:\n\"semisweet chocolate chips\"\n,\n\"quantity\"\n:\n\"2 cups\"\n}\n],\n\"instructions\"\n:\n[\n\"Preheat the oven to 375°F (190°C).\"\n,\n\"In a small bowl, whisk together the flour, baking soda, and salt.\"\n,\n\"In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy.\"\n,\n\"Beat in the vanilla and eggs, one at a time.\"\n,\n\"Gradually beat in the dry ingredients until just combined.\"\n,\n\"Stir in the chocolate chips.\"\n,\n\"Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes.\"\n]\n}\nStreaming\nYou can stream structured outputs, which allows you to start processing the\nresponse as it's being generated, without having to wait for the entire output\nto be complete. This can improve the perceived performance of your application.\nThe streamed chunks will be valid partial JSON strings, which can be\nconcatenated to form the final, complete JSON object.\nfrom\ngoogle\nimport\ngenai\nfrom\npydantic\nimport\nBaseModel\n,\nField\nfrom\ntyping\nimport\nLiteral\nclass\nFeedback\n(\nBaseModel\n):\nsentiment\n:\nLiteral\n[\n\"positive\"\n,\n\"neutral\"\n,\n\"negative\"\n]\nsummary\n:\nstr\nclient\n=\ngenai\n.\nClient\n()\nprompt\n=\n\"The new UI is incredibly intuitive and visually appealing. Great job. Add a very long summary to test streaming!\"\nresponse_stream\n=\nclient\n.\nmodels\n.\ngenerate_content_stream\n(\nmodel\n=\n\"gemini-3-flash-preview\"\n,\ncontents\n=\nprompt\n,\nconfig\n=\n{\n\"response_mime_type\"\n:\n\"application\/json\"\n,\n\"response_json_schema\"\n:\nFeedback\n.\nmodel_json_schema\n(),\n},\n)\nfor\nchunk\nin\nresponse_stream\n:\nprint\n(\nchunk\n.\ncandidates\n[\n0\n]\n.\ncontent\n.\nparts\n[\n0\n]\n.\ntext\n)\nimport\n{\nGoogleGenAI\n}\nfrom\n\"@google\/genai\"\n;\nimport\n{\nz\n}\nfrom\n\"zod\"\n;\nimport\n{\nzodToJsonSchema\n}\nfrom\n\"zod-to-json-schema\"\n;\nconst\nai\n=\nnew\nGoogleGenAI\n({});\nconst\nprompt\n=\n\"The new UI is incredibly intuitive and visually appealing. Great job! Add a very long summary to test streaming!\"\n;\nconst\nfeedbackSchema\n=\nz\n.\nobject\n({\nsentiment\n:\nz\n.\nenum\n([\n\"positive\"\n,\n\"neutral\"\n,\n\"negative\"\n]),\nsummary\n:\nz\n.\nstring\n(),\n});\nconst\nstream\n=\nawait\nai\n.\nmodels\n.\ngenerateContentStream\n({\nmodel\n:\n\"gemini-3-flash-preview\"\n,\ncontents\n:\nprompt\n,\nconfig\n:\n{\nresponseMimeType\n:\n\"application\/json\"\n,\nresponseJsonSchema\n:\nzodToJsonSchema\n(\nfeedbackSchema\n),\n},\n});\nfor\nawait\n(\nconst\nchunk\nof\nstream\n)\n{\nconsole\n.\nlog\n(\nchunk\n.\ncandidates\n[\n0\n].\ncontent\n.\nparts\n[\n0\n].\ntext\n)\n}\nStructured outputs with tools\nGemini 3 lets you combine Structured Outputs with built-in tools, including\nGrounding with Google Search\n,\nURL Context\n,\nCode Execution\n,\nFile Search\n, and\nFunction Calling\n.\nfrom\ngoogle\nimport\ngenai\nfrom\npydantic\nimport\nBaseModel\n,\nField\nfrom\ntyping\nimport\nList\nclass\nMatchResult\n(\nBaseModel\n):\nwinner\n:\nstr\n=\nField\n(\ndescription\n=\n\"The name of the winner.\"\n)\nfinal_match_score\n:\nstr\n=\nField\n(\ndescription\n=\n\"The final match score.\"\n)\nscorers\n:\nList\n[\nstr\n]\n=\nField\n(\ndescription\n=\n\"The name of the scorer.\"\n)\nclient\n=\ngenai\n.\nClient\n()\nresponse\n=\nclient\n.\nmodels\n.\ngenerate_content\n(\nmodel\n=\n\"gemini-3.1-pro-preview\"\n,\ncontents\n=\n\"Search for all details for the latest Euro.\"\n,\nconfig\n=\n{\n\"tools\"\n:\n[\n{\n\"google_search\"\n:\n{}},\n{\n\"url_context\"\n:\n{}}\n],\n\"response_mime_type\"\n:\n\"application\/json\"\n,\n\"response_json_schema\"\n:\nMatchResult\n.\nmodel_json_schema\n(),\n},\n)\nresult\n=\nMatchResult\n.\nmodel_validate_json\n(\nresponse\n.\ntext\n)\nprint\n(\nresult\n)\nimport\n{\nGoogleGenAI\n}\nfrom\n\"@google\/genai\"\n;\nimport\n{\nz\n}\nfrom\n\"zod\"\n;\nimport\n{\nzodToJsonSchema\n}\nfrom\n\"zod-to-json-schema\"\n;\nconst\nai\n=\nnew\nGoogleGenAI\n({});\nconst\nmatchSchema\n=\nz\n.\nobject\n({\nwinner\n:\nz\n.\nstring\n().\ndescribe\n(\n\"The name of the winner.\"\n),\nfinal_match_score\n:\nz\n.\nstring\n().\ndescribe\n(\n\"The final score.\"\n),\nscorers\n:\nz\n.\narray\n(\nz\n.\nstring\n()).\ndescribe\n(\n\"The name of the scorer.\"\n)\n});\nasync\nfunction\nrun\n()\n{\nconst\nresponse\n=\nawait\nai\n.\nmodels\n.\ngenerateContent\n({\nmodel\n:\n\"gemini-3.1-pro-preview\"\n,\ncontents\n:\n\"Search for all details for the latest Euro.\"\n,\nconfig\n:\n{\ntools\n:\n[\n{\ngoogleSearch\n:\n{}\n},\n{\nurlContext\n:\n{}\n}\n],\nresponseMimeType\n:\n\"application\/json\"\n,\nresponseJsonSchema\n:\nzodToJsonSchema\n(\nmatchSchema\n),\n},\n});\nconst\nmatch\n=\nmatchSchema\n.\nparse\n(\nJSON\n.\nparse\n(\nresponse\n.\ntext\n));\nconsole\n.\nlog\n(\nmatch\n);\n}\nrun\n();\ncurl\n\"https:\/\/generativelanguage.googleapis.com\/v1beta\/models\/gemini-3.1-pro-preview:generateContent\"\n\\\n-H\n\"x-goog-api-key:\n$GEMINI_API_KEY\n\"\n\\\n-H\n'Content-Type: application\/json'\n\\\n-X\nPOST\n\\\n-d\n'{\n\"contents\": [{\n\"parts\": [{\"text\": \"Search for all details for the latest Euro.\"}]\n}],\n\"tools\": [\n{\"googleSearch\": {}},\n{\"urlContext\": {}}\n],\n\"generationConfig\": {\n\"responseMimeType\": \"application\/json\",\n\"responseJsonSchema\": {\n\"type\": \"object\",\n\"properties\": {\n\"winner\": {\"type\": \"string\", \"description\": \"The name of the winner.\"},\n\"final_match_score\": {\"type\": \"string\", \"description\": \"The final score.\"},\n\"scorers\": {\n\"type\": \"array\",\n\"items\": {\"type\": \"string\"},\n\"description\": \"The name of the scorer.\"\n}\n},\n\"required\": [\"winner\", \"final_match_score\", \"scorers\"]\n}\n}\n}'\nJSON schema support\nTo generate a JSON object, set the\nresponse_mime_type\nin the generation configuration to\napplication\/json\nand provide a\nresponse_json_schema\n. The schema must be a valid\nJSON Schema\nthat describes the desired output format.\nThe model will then generate a response that is a syntactically valid JSON string matching the provided schema. When using structured outputs, the model will produce outputs in the same order as the keys in the schema.\nGemini's structured output mode supports a subset of the\nJSON Schema\nspecification.\nThe following values of\ntype\nare supported:\nstring\n: For text.\nnumber\n: For floating-point numbers.\ninteger\n: For whole numbers.\nboolean\n: For true\/false values.\nobject\n: For structured data with key-value pairs.\narray\n: For lists of items.\nnull\n: To allow a property to be null, include\n\"null\"\nin the type array (e.g.,\n{\"type\": [\"string\", \"null\"]}\n).\nThese descriptive properties help guide the model:\ntitle\n: A short description of a property.\ndescription\n: A longer and more detailed description of a property.\nType-specific properties\nFor\nobject\nvalues:\nproperties\n: An object where each key is a property name and each value is a schema for that property.\nrequired\n: An array of strings, listing which properties are mandatory.\nadditionalProperties\n: Controls whether properties not listed in\nproperties\nare allowed. Can be a boolean or a schema.\nFor\nstring\nvalues:\nenum\n: Lists a specific set of possible strings for classification tasks.\nformat\n: Specifies a syntax for the string, such as\ndate-time\n,\ndate\n,\ntime\n.\nFor\nnumber\nand\ninteger\nvalues:\nenum\n: Lists a specific set of possible numeric values.\nminimum\n: The minimum inclusive value.\nmaximum\n: The maximum inclusive value.\nFor\narray\nvalues:\nitems\n: Defines the schema for all items in the array.\nprefixItems\n: Defines a list of schemas for the first N items, allowing for tuple-like structures.\nminItems\n: The minimum number of items in the array.\nmaxItems\n: The maximum number of items in the array.\nModel support\nThe following models support structured output:\nModel\nStructured Outputs\nGemini 3.1 Pro Preview\n✔️\nGemini 3 Flash Preview\n✔️\nGemini 2.5 Pro\n✔️\nGemini 2.5 Flash\n✔️\nGemini 2.5 Flash-Lite\n✔️\nGemini 2.0 Flash\n✔️*\nGemini 2.0 Flash-Lite\n✔️*\n* Note that Gemini 2.0 requires an explicit\npropertyOrdering\nlist within the JSON input to define the preferred structure. You can find an example in this\ncookbook\n.\nStructured outputs vs.\nfunction calling\nBoth structured outputs and function calling use JSON schemas, but they serve different purposes:\nFeature\nPrimary Use Case\nStructured Outputs\nFormatting the final response to the user.\nUse this when you want the model's\nanswer\nto be in a specific format (e.g., extracting data from a document to save to a database).\nFunction Calling\nTaking action during the conversation.\nUse this when the model needs to\nask you\nto perform a task (e.g., \"get current weather\") before it can provide a final answer.\nBest practices\nClear descriptions:\nUse the\ndescription\nfield in your schema to provide clear instructions to the model about what each property represents. This is crucial for guiding the model's output.\nStrong typing:\nUse specific types (\ninteger\n,\nstring\n,\nenum\n) whenever possible. If a parameter has a limited set of valid values, use an\nenum\n.\nPrompt engineering:\nClearly state in your prompt what you want the model to do. For example, \"Extract the following information from the text...\" or \"Classify this feedback according to the provided schema...\".\nValidation:\nWhile structured output guarantees syntactically correct JSON, it does not guarantee the values are semantically correct. Always validate the final output in your application code before using it.\nError handling:\nImplement robust error handling in your application to gracefully manage cases where the model's output, while schema-compliant, may not meet your business logic requirements.\nLimitations\nSchema subset:\nNot all features of the JSON Schema specification are supported. The model ignores unsupported properties.\nSchema complexity:\nThe 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.\nExcept as otherwise noted, the content of this page is licensed under the\nCreative Commons Attribution 4.0 License\n, and code samples are licensed under the\nApache 2.0 License\n. For details, see the\nGoogle Developers Site Policies\n. Java is a registered trademark of Oracle and\/or its affiliates.\nLast updated 2026-02-26 UTC.\n[[[\"Easy to understand\",\"easyToUnderstand\",\"thumb-up\"],[\"Solved my problem\",\"solvedMyProblem\",\"thumb-up\"],[\"Other\",\"otherUp\",\"thumb-up\"]],[[\"Missing the information I need\",\"missingTheInformationINeed\",\"thumb-down\"],[\"Too complicated \/ too many steps\",\"tooComplicatedTooManySteps\",\"thumb-down\"],[\"Out of date\",\"outOfDate\",\"thumb-down\"],[\"Samples \/ code issue\",\"samplesCodeIssue\",\"thumb-down\"],[\"Other\",\"otherDown\",\"thumb-down\"]],[\"Last updated 2026-02-26 UTC.\"],[],[]]","attrs_markdown":"[Skip to main content](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#main-content)\n\n[![Gemini API](https:\/\/ai.google.dev\/_static\/googledevai\/images\/gemini-api-logo.svg)](https:\/\/ai.google.dev\/)\n\n- [English](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output)\n- [Deutsch](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=de)\n- [Español – América Latina](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=es-419)\n- [Français](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=fr)\n- [Indonesia](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=id)\n- [Italiano](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=it)\n- [Polski](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=pl)\n- [Português – Brasil](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=pt-br)\n- [Shqip](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=sq)\n- [Tiếng Việt](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=vi)\n- [Türkçe](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=tr)\n- [Русский](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=ru)\n- [עברית](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=he)\n- [العربيّة](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=ar)\n- [فارسی](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=fa)\n- [हिंदी](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=hi)\n- [বাংলা](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=bn)\n- [ภาษาไทย](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=th)\n- [中文 – 简体](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=zh-cn)\n- [中文 – 繁體](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=zh-tw)\n- [日本語](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=ja)\n- [한국어](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=ko)\n\n[Get API key](https:\/\/aistudio.google.com\/apikey)   [Cookbook](https:\/\/github.com\/google-gemini\/cookbook)   [Community](https:\/\/discuss.ai.google.dev\/c\/gemini-api\/)\n\n[Sign in](https:\/\/ai.google.dev\/_d\/signin?continue=https%3A%2F%2Fai.google.dev%2Fgemini-api%2Fdocs%2Fstructured-output%3Fexample%3Drecipe&prompt=select_account)\n\n[Docs](https:\/\/ai.google.dev\/gemini-api\/docs)\n\n[API reference](https:\/\/ai.google.dev\/api)\n\nMore\n\n[![Gemini API](https:\/\/ai.google.dev\/_static\/googledevai\/images\/gemini-api-logo.svg)](https:\/\/ai.google.dev\/)\n\n- [Gemini API](https:\/\/ai.google.dev\/gemini-api\/docs)\n  - [Docs](https:\/\/ai.google.dev\/gemini-api\/docs)\n  - [API reference](https:\/\/ai.google.dev\/api)\n- [Get API key](https:\/\/aistudio.google.com\/apikey)\n- [Cookbook](https:\/\/github.com\/google-gemini\/cookbook)\n- [Community](https:\/\/discuss.ai.google.dev\/c\/gemini-api\/)\n\n- Get started\n- [Overview](https:\/\/ai.google.dev\/gemini-api\/docs)\n- [Quickstart](https:\/\/ai.google.dev\/gemini-api\/docs\/quickstart)\n- [API keys](https:\/\/ai.google.dev\/gemini-api\/docs\/api-key)\n- [Libraries](https:\/\/ai.google.dev\/gemini-api\/docs\/libraries)\n- [Pricing](https:\/\/ai.google.dev\/gemini-api\/docs\/pricing)\n- [Interactions API](https:\/\/ai.google.dev\/gemini-api\/docs\/interactions)\n- [Coding agent setup](https:\/\/ai.google.dev\/gemini-api\/docs\/coding-agents)\n- Models\n- [All models](https:\/\/ai.google.dev\/gemini-api\/docs\/models)\n- [Gemini 3](https:\/\/ai.google.dev\/gemini-api\/docs\/gemini-3)\n- [Nano Banana](https:\/\/ai.google.dev\/gemini-api\/docs\/image-generation)\n- [Veo](https:\/\/ai.google.dev\/gemini-api\/docs\/video)\n- [Lyria 3](https:\/\/ai.google.dev\/gemini-api\/docs\/music-generation)\n- [Lyria Real Time](https:\/\/ai.google.dev\/gemini-api\/docs\/realtime-music-generation)\n- [Imagen](https:\/\/ai.google.dev\/gemini-api\/docs\/imagen)\n- [Text-to-speech](https:\/\/ai.google.dev\/gemini-api\/docs\/speech-generation)\n- [Embeddings](https:\/\/ai.google.dev\/gemini-api\/docs\/embeddings)\n- [Robotics](https:\/\/ai.google.dev\/gemini-api\/docs\/robotics-overview)\n- Core capabilities\n- [Text](https:\/\/ai.google.dev\/gemini-api\/docs\/text-generation)\n- Image\n  \n  - [Image generation 🍌](https:\/\/ai.google.dev\/gemini-api\/docs\/image-generation)\n  - [Image understanding](https:\/\/ai.google.dev\/gemini-api\/docs\/image-understanding)\n- Video\n  \n  - [Video generation](https:\/\/ai.google.dev\/gemini-api\/docs\/video)\n  - [Video understanding](https:\/\/ai.google.dev\/gemini-api\/docs\/video-understanding)\n- [Documents](https:\/\/ai.google.dev\/gemini-api\/docs\/document-processing)\n- Speech and audio\n  \n  - [Speech generation](https:\/\/ai.google.dev\/gemini-api\/docs\/speech-generation)\n  - [Audio understanding](https:\/\/ai.google.dev\/gemini-api\/docs\/audio)\n- Thinking\n  \n  - [Thinking](https:\/\/ai.google.dev\/gemini-api\/docs\/thinking)\n  - [Thought signatures](https:\/\/ai.google.dev\/gemini-api\/docs\/thought-signatures)\n- [Structured outputs](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output)\n- [Function calling](https:\/\/ai.google.dev\/gemini-api\/docs\/function-calling)\n- [Long context](https:\/\/ai.google.dev\/gemini-api\/docs\/long-context)\n- Agents\n- [Overview](https:\/\/ai.google.dev\/gemini-api\/docs\/agents)\n- [Deep Research Agent](https:\/\/ai.google.dev\/gemini-api\/docs\/deep-research)\n- Tools\n- [Overview](https:\/\/ai.google.dev\/gemini-api\/docs\/tools)\n- [Google Search](https:\/\/ai.google.dev\/gemini-api\/docs\/google-search)\n- [Google Maps](https:\/\/ai.google.dev\/gemini-api\/docs\/maps-grounding)\n- [Code execution](https:\/\/ai.google.dev\/gemini-api\/docs\/code-execution)\n- [URL context](https:\/\/ai.google.dev\/gemini-api\/docs\/url-context)\n- [Computer Use](https:\/\/ai.google.dev\/gemini-api\/docs\/computer-use)\n- [File Search](https:\/\/ai.google.dev\/gemini-api\/docs\/file-search)\n- [Combine Tools and Function calling](https:\/\/ai.google.dev\/gemini-api\/docs\/tool-combination)\n- Live API\n- [Overview](https:\/\/ai.google.dev\/gemini-api\/docs\/live-api)\n- Get started\n  \n  - [Get started using the GenAI SDK](https:\/\/ai.google.dev\/gemini-api\/docs\/live-api\/get-started-sdk)\n  - [Get started using raw WebSockets](https:\/\/ai.google.dev\/gemini-api\/docs\/live-api\/get-started-websocket)\n- [Capabilities](https:\/\/ai.google.dev\/gemini-api\/docs\/live-api\/capabilities)\n- [Tool use](https:\/\/ai.google.dev\/gemini-api\/docs\/live-api\/tools)\n- [Session management](https:\/\/ai.google.dev\/gemini-api\/docs\/live-api\/session-management)\n- [Ephemeral tokens](https:\/\/ai.google.dev\/gemini-api\/docs\/live-api\/ephemeral-tokens)\n- [Best practices](https:\/\/ai.google.dev\/gemini-api\/docs\/live-api\/best-practices)\n- Optimization\n- [Overview](https:\/\/ai.google.dev\/gemini-api\/docs\/optimization)\n- [Batch API](https:\/\/ai.google.dev\/gemini-api\/docs\/batch-api)\n- [Flex inference](https:\/\/ai.google.dev\/gemini-api\/docs\/flex-inference)\n- [Priority inference](https:\/\/ai.google.dev\/gemini-api\/docs\/priority-inference)\n- [Context caching](https:\/\/ai.google.dev\/gemini-api\/docs\/caching)\n- Guides\n- File input\n  \n  - [Input methods](https:\/\/ai.google.dev\/gemini-api\/docs\/file-input-methods)\n  - [Files API](https:\/\/ai.google.dev\/gemini-api\/docs\/files)\n- [Open AI compatibility](https:\/\/ai.google.dev\/gemini-api\/docs\/openai)\n- [Media resolution](https:\/\/ai.google.dev\/gemini-api\/docs\/media-resolution)\n- [Token counting](https:\/\/ai.google.dev\/gemini-api\/docs\/tokens)\n- [Prompt engineering](https:\/\/ai.google.dev\/gemini-api\/docs\/prompting-strategies)\n- Logs and datasets\n  \n  - [Get started with logs](https:\/\/ai.google.dev\/gemini-api\/docs\/logs-datasets)\n  - [Data logging and sharing](https:\/\/ai.google.dev\/gemini-api\/docs\/logs-policy)\n- Safety\n  \n  - [Safety settings](https:\/\/ai.google.dev\/gemini-api\/docs\/safety-settings)\n  - [Safety guidance](https:\/\/ai.google.dev\/gemini-api\/docs\/safety-guidance)\n- Frameworks\n  \n  - [LangChain & LangGraph](https:\/\/ai.google.dev\/gemini-api\/docs\/langgraph-example)\n  - [CrewAI](https:\/\/ai.google.dev\/gemini-api\/docs\/crewai-example)\n  - [LlamaIndex](https:\/\/ai.google.dev\/gemini-api\/docs\/llama-index)\n  - [Vercel AI SDK](https:\/\/ai.google.dev\/gemini-api\/docs\/vercel-ai-sdk-example)\n  - [Temporal](https:\/\/ai.google.dev\/gemini-api\/docs\/temporal-example)\n- Resources\n- [Release notes](https:\/\/ai.google.dev\/gemini-api\/docs\/changelog)\n- [Deprecations](https:\/\/ai.google.dev\/gemini-api\/docs\/deprecations)\n- [Rate limits](https:\/\/ai.google.dev\/gemini-api\/docs\/rate-limits)\n- [Billing info](https:\/\/ai.google.dev\/gemini-api\/docs\/billing)\n- [Migrate to Gen AI SDK](https:\/\/ai.google.dev\/gemini-api\/docs\/migrate)\n- [API troubleshooting](https:\/\/ai.google.dev\/gemini-api\/docs\/troubleshooting)\n- [Partner and library integrations](https:\/\/ai.google.dev\/gemini-api\/docs\/partner-integration)\n- Google AI Studio\n  \n  - [Quickstart](https:\/\/ai.google.dev\/gemini-api\/docs\/ai-studio-quickstart)\n  - [Vibe code in Build mode](https:\/\/ai.google.dev\/gemini-api\/docs\/aistudio-build-mode)\n  - [Developing Full-Stack Apps](https:\/\/ai.google.dev\/gemini-api\/docs\/aistudio-fullstack)\n  - [Troubleshooting](https:\/\/ai.google.dev\/gemini-api\/docs\/troubleshoot-ai-studio)\n  - [Access for Workspace users](https:\/\/ai.google.dev\/gemini-api\/docs\/workspace)\n- Google Cloud Platform\n  \n  - [VertexAI Gemini API](https:\/\/ai.google.dev\/gemini-api\/docs\/migrate-to-cloud)\n  - [OAuth authentication](https:\/\/ai.google.dev\/gemini-api\/docs\/oauth)\n- Policies\n- [Terms of service](https:\/\/ai.google.dev\/gemini-api\/terms)\n- [Available regions](https:\/\/ai.google.dev\/gemini-api\/docs\/available-regions)\n- [Abuse monitoring](https:\/\/ai.google.dev\/gemini-api\/docs\/usage-policies)\n- [Feedback information](https:\/\/ai.google.dev\/gemini-api\/docs\/feedback-policies)\n\n- On this page\n- [Streaming](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#streaming)\n- [Structured outputs with tools](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#structured_outputs_with_tools)\n- [JSON schema support](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#json_schema_support)\n  - [Type-specific properties](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#type-specific_properties)\n- [Model support](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#model_support)\n- [Structured outputs vs. function calling](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#structured_outputs_vs_function_calling)\n- [Best practices](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#best_practices)\n- [Limitations](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#limitations)\n\nTry the new high-speed, cost-effective [Veo 3.1 Lite](https:\/\/ai.google.dev\/gemini-api\/docs\/models\/veo-3.1-lite-generate-preview) model for video generation at scale.\n\n- [Home](https:\/\/ai.google.dev\/)\n- [Gemini API](https:\/\/ai.google.dev\/gemini-api)\n- [Docs](https:\/\/ai.google.dev\/gemini-api\/docs)\n\nWas this helpful?\n\nSend feedback\n\n# Structured outputs\n- On this page\n- [Streaming](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#streaming)\n- [Structured outputs with tools](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#structured_outputs_with_tools)\n- [JSON schema support](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#json_schema_support)\n  - [Type-specific properties](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#type-specific_properties)\n- [Model support](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#model_support)\n- [Structured outputs vs. function calling](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#structured_outputs_vs_function_calling)\n- [Best practices](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#best_practices)\n- [Limitations](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#limitations)\n\nYou can configure Gemini models to generate responses that adhere to a provided JSON Schema. This ensures predictable, type-safe results and simplifies extracting structured data from unstructured text.\n\nUsing structured outputs is ideal for:\n\n- **Data extraction:** Pull specific information like names and dates from text.\n- **Structured classification:** Classify text into predefined categories.\n- **Agentic workflows:** Generate structured inputs for tools or APIs.\n\nIn addition to supporting JSON Schema in the REST API, the Google GenAI SDKs make it easy to define schemas using [Pydantic](https:\/\/docs.pydantic.dev\/latest\/) (Python) and [Zod](https:\/\/zod.dev\/) (JavaScript).\n\nRecipe Extractor Content Moderation Recursive Structures\n\nThis example demonstrates how to extract structured data from text using basic JSON Schema types like `object`, `array`, `string`, and `integer`.\n\n[Python](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#python)\n\n[JavaScript](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#javascript)\n\n[Go](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#go)\n\n[REST](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#rest)\n\nMore\n```\nfrom google import genai\nfrom pydantic import BaseModel, Field\nfrom typing import List, Optional\n\nclass Ingredient(BaseModel):\n    name: str = Field(description=\"Name of the ingredient.\")\n    quantity: str = Field(description=\"Quantity of the ingredient, including units.\")\n\nclass Recipe(BaseModel):\n    recipe_name: str = Field(description=\"The name of the recipe.\")\n    prep_time_minutes: Optional[int] = Field(description=\"Optional time in minutes to prepare the recipe.\")\n    ingredients: List[Ingredient]\n    instructions: List[str]\n\nclient = genai.Client()\n\nprompt = \"\"\"\nPlease extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1\/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3\/4 cup of granulated sugar,\n3\/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they'll need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes.\n\"\"\"\n\nresponse = client.models.generate_content(\n    model=\"gemini-3-flash-preview\",\n    contents=prompt,\n    config={\n        \"response_mime_type\": \"application\/json\",\n        \"response_json_schema\": Recipe.model_json_schema(),\n    },\n)\n\nrecipe = Recipe.model_validate_json(response.text)\nprint(recipe)\n```\n```\nimport { GoogleGenAI } from \"@google\/genai\";\nimport { z } from \"zod\";\nimport { zodToJsonSchema } from \"zod-to-json-schema\";\n\nconst ingredientSchema = z.object({\n  name: z.string().describe(\"Name of the ingredient.\"),\n  quantity: z.string().describe(\"Quantity of the ingredient, including units.\"),\n});\n\nconst recipeSchema = z.object({\n  recipe_name: z.string().describe(\"The name of the recipe.\"),\n  prep_time_minutes: z.number().optional().describe(\"Optional time in minutes to prepare the recipe.\"),\n  ingredients: z.array(ingredientSchema),\n  instructions: z.array(z.string()),\n});\n\nconst ai = new GoogleGenAI({});\n\nconst prompt = `\nPlease extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1\/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3\/4 cup of granulated sugar,\n3\/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they'll need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes.\n`;\n\nconst response = await ai.models.generateContent({\n  model: \"gemini-3-flash-preview\",\n  contents: prompt,\n  config: {\n    responseMimeType: \"application\/json\",\n    responseJsonSchema: zodToJsonSchema(recipeSchema),\n  },\n});\n\nconst recipe = recipeSchema.parse(JSON.parse(response.text));\nconsole.log(recipe);\n```\n```\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"log\"\n\n    \"google.golang.org\/genai\"\n)\n\nfunc main() {\n    ctx := context.Background()\n    client, err := genai.NewClient(ctx, nil)\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    prompt := `\n  Please extract the recipe from the following text.\n  The user wants to make delicious chocolate chip cookies.\n  They need 2 and 1\/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n  1 teaspoon of salt, 1 cup of unsalted butter (softened), 3\/4 cup of granulated sugar,\n  3\/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\n  For the best part, they'll need 2 cups of semisweet chocolate chips.\n  First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\n  baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\n  until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\n  ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\n  onto ungreased baking sheets and bake for 9 to 11 minutes.\n  `\n    config := &genai.GenerateContentConfig{\n        ResponseMIMEType: \"application\/json\",\n        ResponseJsonSchema: map[string]any{\n            \"type\": \"object\",\n            \"properties\": map[string]any{\n                \"recipe_name\": map[string]any{\n                    \"type\":        \"string\",\n                    \"description\": \"The name of the recipe.\",\n                },\n                \"prep_time_minutes\": map[string]any{\n                    \"type\":        \"integer\",\n                    \"description\": \"Optional time in minutes to prepare the recipe.\",\n                },\n                \"ingredients\": map[string]any{\n                    \"type\": \"array\",\n                    \"items\": map[string]any{\n                        \"type\": \"object\",\n                        \"properties\": map[string]any{\n                            \"name\": map[string]any{\n                                \"type\":        \"string\",\n                                \"description\": \"Name of the ingredient.\",\n                            },\n                            \"quantity\": map[string]any{\n                                \"type\":        \"string\",\n                                \"description\": \"Quantity of the ingredient, including units.\",\n                            },\n                        },\n                        \"required\": []string{\"name\", \"quantity\"},\n                    },\n                },\n                \"instructions\": map[string]any{\n                    \"type\":  \"array\",\n                    \"items\": map[string]any{\"type\": \"string\"},\n                },\n            },\n            \"required\": []string{\"recipe_name\", \"ingredients\", \"instructions\"},\n        },\n    }\n\n    result, err := client.Models.GenerateContent(\n        ctx,\n        \"gemini-3-flash-preview\",\n        genai.Text(prompt),\n        config,\n    )\n    if err != nil {\n        log.Fatal(err)\n    }\n    fmt.Println(result.Text())\n}\n```\n```\ncurl \"https:\/\/generativelanguage.googleapis.com\/v1beta\/models\/gemini-3-flash-preview:generateContent\" \\\n    -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n    -H 'Content-Type: application\/json' \\\n    -X POST \\\n    -d '{\n      \"contents\": [{\n        \"parts\":[\n          { \"text\": \"Please extract the recipe from the following text.\\nThe user wants to make delicious chocolate chip cookies.\\nThey need 2 and 1\/4 cups of all-purpose flour, 1 teaspoon of baking soda,\\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3\/4 cup of granulated sugar,\\n3\/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\\nFor the best part, they will need 2 cups of semisweet chocolate chips.\\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\\nonto ungreased baking sheets and bake for 9 to 11 minutes.\" }\n        ]\n      }],\n      \"generationConfig\": {\n        \"responseMimeType\": \"application\/json\",\n        \"responseJsonSchema\": {\n          \"type\": \"object\",\n          \"properties\": {\n            \"recipe_name\": {\n              \"type\": \"string\",\n              \"description\": \"The name of the recipe.\"\n            },\n            \"prep_time_minutes\": {\n                \"type\": \"integer\",\n                \"description\": \"Optional time in minutes to prepare the recipe.\"\n            },\n            \"ingredients\": {\n              \"type\": \"array\",\n              \"items\": {\n                \"type\": \"object\",\n                \"properties\": {\n                  \"name\": { \"type\": \"string\", \"description\": \"Name of the ingredient.\"},\n                  \"quantity\": { \"type\": \"string\", \"description\": \"Quantity of the ingredient, including units.\"}\n                },\n                \"required\": [\"name\", \"quantity\"]\n              }\n            },\n            \"instructions\": {\n              \"type\": \"array\",\n              \"items\": { \"type\": \"string\" }\n            }\n          },\n          \"required\": [\"recipe_name\", \"ingredients\", \"instructions\"]\n        }\n      }\n    }'\n```\n\n**Example Response:**\n```\n{\n  \"recipe_name\": \"Delicious Chocolate Chip Cookies\",\n  \"ingredients\": [\n    {\n      \"name\": \"all-purpose flour\",\n      \"quantity\": \"2 and 1\/4 cups\"\n    },\n    {\n      \"name\": \"baking soda\",\n      \"quantity\": \"1 teaspoon\"\n    },\n    {\n      \"name\": \"salt\",\n      \"quantity\": \"1 teaspoon\"\n    },\n    {\n      \"name\": \"unsalted butter (softened)\",\n      \"quantity\": \"1 cup\"\n    },\n    {\n      \"name\": \"granulated sugar\",\n      \"quantity\": \"3\/4 cup\"\n    },\n    {\n      \"name\": \"packed brown sugar\",\n      \"quantity\": \"3\/4 cup\"\n    },\n    {\n      \"name\": \"vanilla extract\",\n      \"quantity\": \"1 teaspoon\"\n    },\n    {\n      \"name\": \"large eggs\",\n      \"quantity\": \"2\"\n    },\n    {\n      \"name\": \"semisweet chocolate chips\",\n      \"quantity\": \"2 cups\"\n    }\n  ],\n  \"instructions\": [\n    \"Preheat the oven to 375°F (190°C).\",\n    \"In a small bowl, whisk together the flour, baking soda, and salt.\",\n    \"In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy.\",\n    \"Beat in the vanilla and eggs, one at a time.\",\n    \"Gradually beat in the dry ingredients until just combined.\",\n    \"Stir in the chocolate chips.\",\n    \"Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes.\"\n  ]\n}\n```\n## Streaming\nYou can stream structured outputs, which allows you to start processing the response as it's being generated, without having to wait for the entire output to be complete. This can improve the perceived performance of your application.\n\nThe streamed chunks will be valid partial JSON strings, which can be concatenated to form the final, complete JSON object.\n\n[Python](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#python)\n\n[JavaScript](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#javascript)\n\nMore\n```\nfrom google import genai\nfrom pydantic import BaseModel, Field\nfrom typing import Literal\n\nclass Feedback(BaseModel):\n    sentiment: Literal[\"positive\", \"neutral\", \"negative\"]\n    summary: str\n\nclient = genai.Client()\nprompt = \"The new UI is incredibly intuitive and visually appealing. Great job. Add a very long summary to test streaming!\"\n\nresponse_stream = client.models.generate_content_stream(\n    model=\"gemini-3-flash-preview\",\n    contents=prompt,\n    config={\n        \"response_mime_type\": \"application\/json\",\n        \"response_json_schema\": Feedback.model_json_schema(),\n    },\n)\n\nfor chunk in response_stream:\n    print(chunk.candidates[0].content.parts[0].text)\n```\n```\nimport { GoogleGenAI } from \"@google\/genai\";\nimport { z } from \"zod\";\nimport { zodToJsonSchema } from \"zod-to-json-schema\";\n\nconst ai = new GoogleGenAI({});\nconst prompt = \"The new UI is incredibly intuitive and visually appealing. Great job! Add a very long summary to test streaming!\";\n\nconst feedbackSchema = z.object({\n  sentiment: z.enum([\"positive\", \"neutral\", \"negative\"]),\n  summary: z.string(),\n});\n\nconst stream = await ai.models.generateContentStream({\n  model: \"gemini-3-flash-preview\",\n  contents: prompt,\n  config: {\n    responseMimeType: \"application\/json\",\n    responseJsonSchema: zodToJsonSchema(feedbackSchema),\n  },\n});\n\nfor await (const chunk of stream) {\n  console.log(chunk.candidates[0].content.parts[0].text)\n}\n```\n## Structured outputs with tools\n**Preview:** This feature is available only to Gemini 3 series models, `gemini-3.1-pro-preview` and `gemini-3-flash-preview`.\n\nGemini 3 lets you combine Structured Outputs with built-in tools, including [Grounding with Google Search](https:\/\/ai.google.dev\/gemini-api\/docs\/google-search), [URL Context](https:\/\/ai.google.dev\/gemini-api\/docs\/url-context), [Code Execution](https:\/\/ai.google.dev\/gemini-api\/docs\/code-execution), [File Search](https:\/\/ai.google.dev\/gemini-api\/docs\/file-search#structured-output), and [Function Calling](https:\/\/ai.google.dev\/gemini-api\/docs\/function-calling).\n\n[Python](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#python)\n\n[JavaScript](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#javascript)\n\n[REST](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#rest)\n\nMore\n```\nfrom google import genai\nfrom pydantic import BaseModel, Field\nfrom typing import List\n\nclass MatchResult(BaseModel):\n    winner: str = Field(description=\"The name of the winner.\")\n    final_match_score: str = Field(description=\"The final match score.\")\n    scorers: List[str] = Field(description=\"The name of the scorer.\")\n\nclient = genai.Client()\n\nresponse = client.models.generate_content(\n    model=\"gemini-3.1-pro-preview\",\n    contents=\"Search for all details for the latest Euro.\",\n    config={\n        \"tools\": [\n            {\"google_search\": {}},\n            {\"url_context\": {}}\n        ],\n        \"response_mime_type\": \"application\/json\",\n        \"response_json_schema\": MatchResult.model_json_schema(),\n    },  \n)\n\nresult = MatchResult.model_validate_json(response.text)\nprint(result)\n```\n```\nimport { GoogleGenAI } from \"@google\/genai\";\nimport { z } from \"zod\";\nimport { zodToJsonSchema } from \"zod-to-json-schema\";\n\nconst ai = new GoogleGenAI({});\n\nconst matchSchema = z.object({\n  winner: z.string().describe(\"The name of the winner.\"),\n  final_match_score: z.string().describe(\"The final score.\"),\n  scorers: z.array(z.string()).describe(\"The name of the scorer.\")\n});\n\nasync function run() {\n  const response = await ai.models.generateContent({\n    model: \"gemini-3.1-pro-preview\",\n    contents: \"Search for all details for the latest Euro.\",\n    config: {\n      tools: [\n        { googleSearch: {} },\n        { urlContext: {} }\n      ],\n      responseMimeType: \"application\/json\",\n      responseJsonSchema: zodToJsonSchema(matchSchema),\n    },\n  });\n\n  const match = matchSchema.parse(JSON.parse(response.text));\n  console.log(match);\n}\n\nrun();\n```\n```\ncurl \"https:\/\/generativelanguage.googleapis.com\/v1beta\/models\/gemini-3.1-pro-preview:generateContent\" \\\n  -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n  -H 'Content-Type: application\/json' \\\n  -X POST \\\n  -d '{\n    \"contents\": [{\n      \"parts\": [{\"text\": \"Search for all details for the latest Euro.\"}]\n    }],\n    \"tools\": [\n      {\"googleSearch\": {}},\n      {\"urlContext\": {}}\n    ],\n    \"generationConfig\": {\n        \"responseMimeType\": \"application\/json\",\n        \"responseJsonSchema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"winner\": {\"type\": \"string\", \"description\": \"The name of the winner.\"},\n                \"final_match_score\": {\"type\": \"string\", \"description\": \"The final score.\"},\n                \"scorers\": {\n                    \"type\": \"array\",\n                    \"items\": {\"type\": \"string\"},\n                    \"description\": \"The name of the scorer.\"\n                }\n            },\n            \"required\": [\"winner\", \"final_match_score\", \"scorers\"]\n        }\n    }\n  }'\n```\n## JSON schema support\nTo generate a JSON object, set the `response_mime_type` in the generation configuration to `application\/json` and provide a `response_json_schema`. The schema must be a valid [JSON Schema](https:\/\/json-schema.org\/) that describes the desired output format.\n\nThe model will then generate a response that is a syntactically valid JSON string matching the provided schema. When using structured outputs, the model will produce outputs in the same order as the keys in the schema.\n\nGemini's structured output mode supports a subset of the [JSON Schema](https:\/\/json-schema.org\/) specification.\n\nThe following values of `type` are supported:\n\n- **`string`**: For text.\n- **`number`**: For floating-point numbers.\n- **`integer`**: For whole numbers.\n- **`boolean`**: For true\/false values.\n- **`object`**: For structured data with key-value pairs.\n- **`array`**: For lists of items.\n- **`null`**: To allow a property to be null, include `\"null\"` in the type array (e.g., `{\"type\": [\"string\", \"null\"]}`).\n\nThese descriptive properties help guide the model:\n\n- **`title`**: A short description of a property.\n- **`description`**: A longer and more detailed description of a property.\n### Type-specific properties\n**For `object` values:**\n\n- **`properties`**: An object where each key is a property name and each value is a schema for that property.\n- **`required`**: An array of strings, listing which properties are mandatory.\n- **`additionalProperties`**: Controls whether properties not listed in `properties` are allowed. Can be a boolean or a schema.\n\n**For `string` values:**\n\n- **`enum`**: Lists a specific set of possible strings for classification tasks.\n- **`format`**: Specifies a syntax for the string, such as `date-time`, `date`, `time`.\n\n**For `number` and `integer` values:**\n\n- **`enum`**: Lists a specific set of possible numeric values.\n- **`minimum`**: The minimum inclusive value.\n- **`maximum`**: The maximum inclusive value.\n\n**For `array` values:**\n\n- **`items`**: Defines the schema for all items in the array.\n- **`prefixItems`**: Defines a list of schemas for the first N items, allowing for tuple-like structures.\n- **`minItems`**: The minimum number of items in the array.\n- **`maxItems`**: The maximum number of items in the array.\n## Model support\nThe following models support structured output:\n\n| Model | Structured Outputs |\n|---|---|\n| Gemini 3.1 Pro Preview | ✔️ |\n| Gemini 3 Flash Preview | ✔️ |\n| Gemini 2.5 Pro | ✔️ |\n| Gemini 2.5 Flash | ✔️ |\n| Gemini 2.5 Flash-Lite | ✔️ |\n| Gemini 2.0 Flash | ✔️\\* |\n| Gemini 2.0 Flash-Lite | ✔️\\* |\n\n*\\* Note that Gemini 2.0 requires an explicit `propertyOrdering` list within the JSON input to define the preferred structure. You can find an example in this [cookbook](https:\/\/github.com\/google-gemini\/cookbook\/blob\/main\/examples\/Pdf_structured_outputs_on_invoices_and_forms.ipynb).*\n\n## Structured outputs vs. function calling\nBoth structured outputs and function calling use JSON schemas, but they serve different purposes:\n\n| Feature | Primary Use Case |\n|---|---|\n| **Structured Outputs** | **Formatting the final response to the user.** Use this when you want the model's *answer* to be in a specific format (e.g., extracting data from a document to save to a database). |\n| **Function Calling** | **Taking action during the conversation.** Use this when the model needs to *ask you* to perform a task (e.g., \"get current weather\") before it can provide a final answer. |\n## Best practices\n- **Clear descriptions:** Use the `description` field in your schema to provide clear instructions to the model about what each property represents. This is crucial for guiding the model's output.\n- **Strong typing:** Use specific types (`integer`, `string`, `enum`) whenever possible. If a parameter has a limited set of valid values, use an `enum`.\n- **Prompt engineering:** Clearly state in your prompt what you want the model to do. For example, \"Extract the following information from the text...\" or \"Classify this feedback according to the provided schema...\".\n- **Validation:** While structured output guarantees syntactically correct JSON, it does not guarantee the values are semantically correct. Always validate the final output in your application code before using it.\n- **Error handling:** Implement robust error handling in your application to gracefully manage cases where the model's output, while schema-compliant, may not meet your business logic requirements.\n## Limitations\n- **Schema subset:** Not all features of the JSON Schema specification are supported. The model ignores unsupported properties.\n- **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.\n\nWas this helpful?\n\nSend feedback\n\nExcept as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https:\/\/creativecommons.org\/licenses\/by\/4.0\/), and code samples are licensed under the [Apache 2.0 License](https:\/\/www.apache.org\/licenses\/LICENSE-2.0). For details, see the [Google Developers Site Policies](https:\/\/developers.google.com\/site-policies). Java is a registered trademark of Oracle and\/or its affiliates.\n\nLast updated 2026-02-26 UTC.\n\n- [Terms](https:\/\/policies.google.com\/terms)\n- [Privacy](https:\/\/policies.google.com\/privacy)\n- [Manage cookies](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output)\n\n- [English](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output)\n- [Deutsch](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=de)\n- [Español – América Latina](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=es-419)\n- [Français](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=fr)\n- [Indonesia](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=id)\n- [Italiano](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=it)\n- [Polski](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=pl)\n- [Português – Brasil](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=pt-br)\n- [Shqip](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=sq)\n- [Tiếng Việt](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=vi)\n- [Türkçe](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=tr)\n- [Русский](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=ru)\n- [עברית](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=he)\n- [العربيّة](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=ar)\n- [فارسی](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=fa)\n- [हिंदी](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=hi)\n- [বাংলা](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=bn)\n- [ภาษาไทย](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=th)\n- [中文 – 简体](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=zh-cn)\n- [中文 – 繁體](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=zh-tw)\n- [日本語](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=ja)\n- [한국어](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output?hl=ko)","attrs_readable_markdown":"[Skip to main content](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#main-content)\n\n- [Gemini API](https:\/\/ai.google.dev\/gemini-api\/docs)\n  - [Docs](https:\/\/ai.google.dev\/gemini-api\/docs)\n  - [API reference](https:\/\/ai.google.dev\/api)\n- [Get API key](https:\/\/aistudio.google.com\/apikey)\n- [Cookbook](https:\/\/github.com\/google-gemini\/cookbook)\n- [Community](https:\/\/discuss.ai.google.dev\/c\/gemini-api\/)\n\n- Get started\n- [Overview](https:\/\/ai.google.dev\/gemini-api\/docs)\n- [Quickstart](https:\/\/ai.google.dev\/gemini-api\/docs\/quickstart)\n- [API keys](https:\/\/ai.google.dev\/gemini-api\/docs\/api-key)\n- [Libraries](https:\/\/ai.google.dev\/gemini-api\/docs\/libraries)\n- [Pricing](https:\/\/ai.google.dev\/gemini-api\/docs\/pricing)\n- [Interactions API](https:\/\/ai.google.dev\/gemini-api\/docs\/interactions)\n- [Coding agent setup](https:\/\/ai.google.dev\/gemini-api\/docs\/coding-agents)\n- Models\n- [All models](https:\/\/ai.google.dev\/gemini-api\/docs\/models)\n- [Gemini 3](https:\/\/ai.google.dev\/gemini-api\/docs\/gemini-3)\n- [Nano Banana](https:\/\/ai.google.dev\/gemini-api\/docs\/image-generation)\n- [Veo](https:\/\/ai.google.dev\/gemini-api\/docs\/video)\n- [Lyria 3](https:\/\/ai.google.dev\/gemini-api\/docs\/music-generation)\n- [Lyria Real Time](https:\/\/ai.google.dev\/gemini-api\/docs\/realtime-music-generation)\n- [Imagen](https:\/\/ai.google.dev\/gemini-api\/docs\/imagen)\n- [Text-to-speech](https:\/\/ai.google.dev\/gemini-api\/docs\/speech-generation)\n- [Embeddings](https:\/\/ai.google.dev\/gemini-api\/docs\/embeddings)\n- [Robotics](https:\/\/ai.google.dev\/gemini-api\/docs\/robotics-overview)\n- Core capabilities\n- [Text](https:\/\/ai.google.dev\/gemini-api\/docs\/text-generation)\n- [Documents](https:\/\/ai.google.dev\/gemini-api\/docs\/document-processing)\n- [Structured outputs](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output)\n- [Function calling](https:\/\/ai.google.dev\/gemini-api\/docs\/function-calling)\n- [Long context](https:\/\/ai.google.dev\/gemini-api\/docs\/long-context)\n- Agents\n- [Overview](https:\/\/ai.google.dev\/gemini-api\/docs\/agents)\n- [Deep Research Agent](https:\/\/ai.google.dev\/gemini-api\/docs\/deep-research)\n- Tools\n- [Overview](https:\/\/ai.google.dev\/gemini-api\/docs\/tools)\n- [Google Search](https:\/\/ai.google.dev\/gemini-api\/docs\/google-search)\n- [Google Maps](https:\/\/ai.google.dev\/gemini-api\/docs\/maps-grounding)\n- [Code execution](https:\/\/ai.google.dev\/gemini-api\/docs\/code-execution)\n- [URL context](https:\/\/ai.google.dev\/gemini-api\/docs\/url-context)\n- [Computer Use](https:\/\/ai.google.dev\/gemini-api\/docs\/computer-use)\n- [File Search](https:\/\/ai.google.dev\/gemini-api\/docs\/file-search)\n- [Combine Tools and Function calling](https:\/\/ai.google.dev\/gemini-api\/docs\/tool-combination)\n- Live API\n- [Overview](https:\/\/ai.google.dev\/gemini-api\/docs\/live-api)\n- [Capabilities](https:\/\/ai.google.dev\/gemini-api\/docs\/live-api\/capabilities)\n- [Tool use](https:\/\/ai.google.dev\/gemini-api\/docs\/live-api\/tools)\n- [Session management](https:\/\/ai.google.dev\/gemini-api\/docs\/live-api\/session-management)\n- [Ephemeral tokens](https:\/\/ai.google.dev\/gemini-api\/docs\/live-api\/ephemeral-tokens)\n- [Best practices](https:\/\/ai.google.dev\/gemini-api\/docs\/live-api\/best-practices)\n- Optimization\n- [Overview](https:\/\/ai.google.dev\/gemini-api\/docs\/optimization)\n- [Batch API](https:\/\/ai.google.dev\/gemini-api\/docs\/batch-api)\n- [Flex inference](https:\/\/ai.google.dev\/gemini-api\/docs\/flex-inference)\n- [Priority inference](https:\/\/ai.google.dev\/gemini-api\/docs\/priority-inference)\n- [Context caching](https:\/\/ai.google.dev\/gemini-api\/docs\/caching)\n- Guides\n- [Open AI compatibility](https:\/\/ai.google.dev\/gemini-api\/docs\/openai)\n- [Media resolution](https:\/\/ai.google.dev\/gemini-api\/docs\/media-resolution)\n- [Token counting](https:\/\/ai.google.dev\/gemini-api\/docs\/tokens)\n- [Prompt engineering](https:\/\/ai.google.dev\/gemini-api\/docs\/prompting-strategies)\n- Resources\n- [Release notes](https:\/\/ai.google.dev\/gemini-api\/docs\/changelog)\n- [Deprecations](https:\/\/ai.google.dev\/gemini-api\/docs\/deprecations)\n- [Rate limits](https:\/\/ai.google.dev\/gemini-api\/docs\/rate-limits)\n- [Billing info](https:\/\/ai.google.dev\/gemini-api\/docs\/billing)\n- [Migrate to Gen AI SDK](https:\/\/ai.google.dev\/gemini-api\/docs\/migrate)\n- [API troubleshooting](https:\/\/ai.google.dev\/gemini-api\/docs\/troubleshooting)\n- [Partner and library integrations](https:\/\/ai.google.dev\/gemini-api\/docs\/partner-integration)\n- Policies\n- [Terms of service](https:\/\/ai.google.dev\/gemini-api\/terms)\n- [Available regions](https:\/\/ai.google.dev\/gemini-api\/docs\/available-regions)\n- [Abuse monitoring](https:\/\/ai.google.dev\/gemini-api\/docs\/usage-policies)\n- [Feedback information](https:\/\/ai.google.dev\/gemini-api\/docs\/feedback-policies)\n\n- On this page\n- [Streaming](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#streaming)\n- [Structured outputs with tools](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#structured_outputs_with_tools)\n- [JSON schema support](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#json_schema_support)\n  - [Type-specific properties](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#type-specific_properties)\n- [Model support](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#model_support)\n- [Structured outputs vs. function calling](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#structured_outputs_vs_function_calling)\n- [Best practices](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#best_practices)\n- [Limitations](https:\/\/ai.google.dev\/gemini-api\/docs\/structured-output#limitations)\n\nYou can configure Gemini models to generate responses that adhere to a provided JSON Schema. This ensures predictable, type-safe results and simplifies extracting structured data from unstructured text.\n\nUsing structured outputs is ideal for:\n\n- **Data extraction:** Pull specific information like names and dates from text.\n- **Structured classification:** Classify text into predefined categories.\n- **Agentic workflows:** Generate structured inputs for tools or APIs.\n\nIn addition to supporting JSON Schema in the REST API, the Google GenAI SDKs make it easy to define schemas using [Pydantic](https:\/\/docs.pydantic.dev\/latest\/) (Python) and [Zod](https:\/\/zod.dev\/) (JavaScript).\n\nThis example demonstrates how to extract structured data from text using basic JSON Schema types like `object`, `array`, `string`, and `integer`.\n\n```\nfrom google import genai\nfrom pydantic import BaseModel, Field\nfrom typing import List, Optional\n\nclass Ingredient(BaseModel):\n    name: str = Field(description=\"Name of the ingredient.\")\n    quantity: str = Field(description=\"Quantity of the ingredient, including units.\")\n\nclass Recipe(BaseModel):\n    recipe_name: str = Field(description=\"The name of the recipe.\")\n    prep_time_minutes: Optional[int] = Field(description=\"Optional time in minutes to prepare the recipe.\")\n    ingredients: List[Ingredient]\n    instructions: List[str]\n\nclient = genai.Client()\n\nprompt = \"\"\"\nPlease extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1\/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3\/4 cup of granulated sugar,\n3\/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they'll need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes.\n\"\"\"\n\nresponse = client.models.generate_content(\n    model=\"gemini-3-flash-preview\",\n    contents=prompt,\n    config={\n        \"response_mime_type\": \"application\/json\",\n        \"response_json_schema\": Recipe.model_json_schema(),\n    },\n)\n\nrecipe = Recipe.model_validate_json(response.text)\nprint(recipe)\n```\n```\nimport { GoogleGenAI } from \"@google\/genai\";\nimport { z } from \"zod\";\nimport { zodToJsonSchema } from \"zod-to-json-schema\";\n\nconst ingredientSchema = z.object({\n  name: z.string().describe(\"Name of the ingredient.\"),\n  quantity: z.string().describe(\"Quantity of the ingredient, including units.\"),\n});\n\nconst recipeSchema = z.object({\n  recipe_name: z.string().describe(\"The name of the recipe.\"),\n  prep_time_minutes: z.number().optional().describe(\"Optional time in minutes to prepare the recipe.\"),\n  ingredients: z.array(ingredientSchema),\n  instructions: z.array(z.string()),\n});\n\nconst ai = new GoogleGenAI({});\n\nconst prompt = `\nPlease extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1\/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3\/4 cup of granulated sugar,\n3\/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they'll need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes.\n`;\n\nconst response = await ai.models.generateContent({\n  model: \"gemini-3-flash-preview\",\n  contents: prompt,\n  config: {\n    responseMimeType: \"application\/json\",\n    responseJsonSchema: zodToJsonSchema(recipeSchema),\n  },\n});\n\nconst recipe = recipeSchema.parse(JSON.parse(response.text));\nconsole.log(recipe);\n```\n```\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"log\"\n\n    \"google.golang.org\/genai\"\n)\n\nfunc main() {\n    ctx := context.Background()\n    client, err := genai.NewClient(ctx, nil)\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    prompt := `\n  Please extract the recipe from the following text.\n  The user wants to make delicious chocolate chip cookies.\n  They need 2 and 1\/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n  1 teaspoon of salt, 1 cup of unsalted butter (softened), 3\/4 cup of granulated sugar,\n  3\/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\n  For the best part, they'll need 2 cups of semisweet chocolate chips.\n  First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\n  baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\n  until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\n  ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\n  onto ungreased baking sheets and bake for 9 to 11 minutes.\n  `\n    config := &genai.GenerateContentConfig{\n        ResponseMIMEType: \"application\/json\",\n        ResponseJsonSchema: map[string]any{\n            \"type\": \"object\",\n            \"properties\": map[string]any{\n                \"recipe_name\": map[string]any{\n                    \"type\":        \"string\",\n                    \"description\": \"The name of the recipe.\",\n                },\n                \"prep_time_minutes\": map[string]any{\n                    \"type\":        \"integer\",\n                    \"description\": \"Optional time in minutes to prepare the recipe.\",\n                },\n                \"ingredients\": map[string]any{\n                    \"type\": \"array\",\n                    \"items\": map[string]any{\n                        \"type\": \"object\",\n                        \"properties\": map[string]any{\n                            \"name\": map[string]any{\n                                \"type\":        \"string\",\n                                \"description\": \"Name of the ingredient.\",\n                            },\n                            \"quantity\": map[string]any{\n                                \"type\":        \"string\",\n                                \"description\": \"Quantity of the ingredient, including units.\",\n                            },\n                        },\n                        \"required\": []string{\"name\", \"quantity\"},\n                    },\n                },\n                \"instructions\": map[string]any{\n                    \"type\":  \"array\",\n                    \"items\": map[string]any{\"type\": \"string\"},\n                },\n            },\n            \"required\": []string{\"recipe_name\", \"ingredients\", \"instructions\"},\n        },\n    }\n\n    result, err := client.Models.GenerateContent(\n        ctx,\n        \"gemini-3-flash-preview\",\n        genai.Text(prompt),\n        config,\n    )\n    if err != nil {\n        log.Fatal(err)\n    }\n    fmt.Println(result.Text())\n}\n```\n```\ncurl \"https:\/\/generativelanguage.googleapis.com\/v1beta\/models\/gemini-3-flash-preview:generateContent\" \\\n    -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n    -H 'Content-Type: application\/json' \\\n    -X POST \\\n    -d '{\n      \"contents\": [{\n        \"parts\":[\n          { \"text\": \"Please extract the recipe from the following text.\\nThe user wants to make delicious chocolate chip cookies.\\nThey need 2 and 1\/4 cups of all-purpose flour, 1 teaspoon of baking soda,\\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3\/4 cup of granulated sugar,\\n3\/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\\nFor the best part, they will need 2 cups of semisweet chocolate chips.\\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\\nonto ungreased baking sheets and bake for 9 to 11 minutes.\" }\n        ]\n      }],\n      \"generationConfig\": {\n        \"responseMimeType\": \"application\/json\",\n        \"responseJsonSchema\": {\n          \"type\": \"object\",\n          \"properties\": {\n            \"recipe_name\": {\n              \"type\": \"string\",\n              \"description\": \"The name of the recipe.\"\n            },\n            \"prep_time_minutes\": {\n                \"type\": \"integer\",\n                \"description\": \"Optional time in minutes to prepare the recipe.\"\n            },\n            \"ingredients\": {\n              \"type\": \"array\",\n              \"items\": {\n                \"type\": \"object\",\n                \"properties\": {\n                  \"name\": { \"type\": \"string\", \"description\": \"Name of the ingredient.\"},\n                  \"quantity\": { \"type\": \"string\", \"description\": \"Quantity of the ingredient, including units.\"}\n                },\n                \"required\": [\"name\", \"quantity\"]\n              }\n            },\n            \"instructions\": {\n              \"type\": \"array\",\n              \"items\": { \"type\": \"string\" }\n            }\n          },\n          \"required\": [\"recipe_name\", \"ingredients\", \"instructions\"]\n        }\n      }\n    }'\n```\n\n**Example Response:**\n```\n{\n  \"recipe_name\": \"Delicious Chocolate Chip Cookies\",\n  \"ingredients\": [\n    {\n      \"name\": \"all-purpose flour\",\n      \"quantity\": \"2 and 1\/4 cups\"\n    },\n    {\n      \"name\": \"baking soda\",\n      \"quantity\": \"1 teaspoon\"\n    },\n    {\n      \"name\": \"salt\",\n      \"quantity\": \"1 teaspoon\"\n    },\n    {\n      \"name\": \"unsalted butter (softened)\",\n      \"quantity\": \"1 cup\"\n    },\n    {\n      \"name\": \"granulated sugar\",\n      \"quantity\": \"3\/4 cup\"\n    },\n    {\n      \"name\": \"packed brown sugar\",\n      \"quantity\": \"3\/4 cup\"\n    },\n    {\n      \"name\": \"vanilla extract\",\n      \"quantity\": \"1 teaspoon\"\n    },\n    {\n      \"name\": \"large eggs\",\n      \"quantity\": \"2\"\n    },\n    {\n      \"name\": \"semisweet chocolate chips\",\n      \"quantity\": \"2 cups\"\n    }\n  ],\n  \"instructions\": [\n    \"Preheat the oven to 375°F (190°C).\",\n    \"In a small bowl, whisk together the flour, baking soda, and salt.\",\n    \"In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy.\",\n    \"Beat in the vanilla and eggs, one at a time.\",\n    \"Gradually beat in the dry ingredients until just combined.\",\n    \"Stir in the chocolate chips.\",\n    \"Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes.\"\n  ]\n}\n```\n## Streaming\nYou can stream structured outputs, which allows you to start processing the response as it's being generated, without having to wait for the entire output to be complete. This can improve the perceived performance of your application.\n\nThe streamed chunks will be valid partial JSON strings, which can be concatenated to form the final, complete JSON object.\n\n```\nfrom google import genai\nfrom pydantic import BaseModel, Field\nfrom typing import Literal\n\nclass Feedback(BaseModel):\n    sentiment: Literal[\"positive\", \"neutral\", \"negative\"]\n    summary: str\n\nclient = genai.Client()\nprompt = \"The new UI is incredibly intuitive and visually appealing. Great job. Add a very long summary to test streaming!\"\n\nresponse_stream = client.models.generate_content_stream(\n    model=\"gemini-3-flash-preview\",\n    contents=prompt,\n    config={\n        \"response_mime_type\": \"application\/json\",\n        \"response_json_schema\": Feedback.model_json_schema(),\n    },\n)\n\nfor chunk in response_stream:\n    print(chunk.candidates[0].content.parts[0].text)\n```\n```\nimport { GoogleGenAI } from \"@google\/genai\";\nimport { z } from \"zod\";\nimport { zodToJsonSchema } from \"zod-to-json-schema\";\n\nconst ai = new GoogleGenAI({});\nconst prompt = \"The new UI is incredibly intuitive and visually appealing. Great job! Add a very long summary to test streaming!\";\n\nconst feedbackSchema = z.object({\n  sentiment: z.enum([\"positive\", \"neutral\", \"negative\"]),\n  summary: z.string(),\n});\n\nconst stream = await ai.models.generateContentStream({\n  model: \"gemini-3-flash-preview\",\n  contents: prompt,\n  config: {\n    responseMimeType: \"application\/json\",\n    responseJsonSchema: zodToJsonSchema(feedbackSchema),\n  },\n});\n\nfor await (const chunk of stream) {\n  console.log(chunk.candidates[0].content.parts[0].text)\n}\n```\n## Structured outputs with tools\nGemini 3 lets you combine Structured Outputs with built-in tools, including [Grounding with Google Search](https:\/\/ai.google.dev\/gemini-api\/docs\/google-search), [URL Context](https:\/\/ai.google.dev\/gemini-api\/docs\/url-context), [Code Execution](https:\/\/ai.google.dev\/gemini-api\/docs\/code-execution), [File Search](https:\/\/ai.google.dev\/gemini-api\/docs\/file-search#structured-output), and [Function Calling](https:\/\/ai.google.dev\/gemini-api\/docs\/function-calling).\n\n```\nfrom google import genai\nfrom pydantic import BaseModel, Field\nfrom typing import List\n\nclass MatchResult(BaseModel):\n    winner: str = Field(description=\"The name of the winner.\")\n    final_match_score: str = Field(description=\"The final match score.\")\n    scorers: List[str] = Field(description=\"The name of the scorer.\")\n\nclient = genai.Client()\n\nresponse = client.models.generate_content(\n    model=\"gemini-3.1-pro-preview\",\n    contents=\"Search for all details for the latest Euro.\",\n    config={\n        \"tools\": [\n            {\"google_search\": {}},\n            {\"url_context\": {}}\n        ],\n        \"response_mime_type\": \"application\/json\",\n        \"response_json_schema\": MatchResult.model_json_schema(),\n    },  \n)\n\nresult = MatchResult.model_validate_json(response.text)\nprint(result)\n```\n```\nimport { GoogleGenAI } from \"@google\/genai\";\nimport { z } from \"zod\";\nimport { zodToJsonSchema } from \"zod-to-json-schema\";\n\nconst ai = new GoogleGenAI({});\n\nconst matchSchema = z.object({\n  winner: z.string().describe(\"The name of the winner.\"),\n  final_match_score: z.string().describe(\"The final score.\"),\n  scorers: z.array(z.string()).describe(\"The name of the scorer.\")\n});\n\nasync function run() {\n  const response = await ai.models.generateContent({\n    model: \"gemini-3.1-pro-preview\",\n    contents: \"Search for all details for the latest Euro.\",\n    config: {\n      tools: [\n        { googleSearch: {} },\n        { urlContext: {} }\n      ],\n      responseMimeType: \"application\/json\",\n      responseJsonSchema: zodToJsonSchema(matchSchema),\n    },\n  });\n\n  const match = matchSchema.parse(JSON.parse(response.text));\n  console.log(match);\n}\n\nrun();\n```\n```\ncurl \"https:\/\/generativelanguage.googleapis.com\/v1beta\/models\/gemini-3.1-pro-preview:generateContent\" \\\n  -H \"x-goog-api-key: $GEMINI_API_KEY\" \\\n  -H 'Content-Type: application\/json' \\\n  -X POST \\\n  -d '{\n    \"contents\": [{\n      \"parts\": [{\"text\": \"Search for all details for the latest Euro.\"}]\n    }],\n    \"tools\": [\n      {\"googleSearch\": {}},\n      {\"urlContext\": {}}\n    ],\n    \"generationConfig\": {\n        \"responseMimeType\": \"application\/json\",\n        \"responseJsonSchema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"winner\": {\"type\": \"string\", \"description\": \"The name of the winner.\"},\n                \"final_match_score\": {\"type\": \"string\", \"description\": \"The final score.\"},\n                \"scorers\": {\n                    \"type\": \"array\",\n                    \"items\": {\"type\": \"string\"},\n                    \"description\": \"The name of the scorer.\"\n                }\n            },\n            \"required\": [\"winner\", \"final_match_score\", \"scorers\"]\n        }\n    }\n  }'\n```\n## JSON schema support\nTo generate a JSON object, set the `response_mime_type` in the generation configuration to `application\/json` and provide a `response_json_schema`. The schema must be a valid [JSON Schema](https:\/\/json-schema.org\/) that describes the desired output format.\n\nThe model will then generate a response that is a syntactically valid JSON string matching the provided schema. When using structured outputs, the model will produce outputs in the same order as the keys in the schema.\n\nGemini's structured output mode supports a subset of the [JSON Schema](https:\/\/json-schema.org\/) specification.\n\nThe following values of `type` are supported:\n\n- **`string`**: For text.\n- **`number`**: For floating-point numbers.\n- **`integer`**: For whole numbers.\n- **`boolean`**: For true\/false values.\n- **`object`**: For structured data with key-value pairs.\n- **`array`**: For lists of items.\n- **`null`**: To allow a property to be null, include `\"null\"` in the type array (e.g., `{\"type\": [\"string\", \"null\"]}`).\n\nThese descriptive properties help guide the model:\n\n- **`title`**: A short description of a property.\n- **`description`**: A longer and more detailed description of a property.\n### Type-specific properties\n**For `object` values:**\n\n- **`properties`**: An object where each key is a property name and each value is a schema for that property.\n- **`required`**: An array of strings, listing which properties are mandatory.\n- **`additionalProperties`**: Controls whether properties not listed in `properties` are allowed. Can be a boolean or a schema.\n\n**For `string` values:**\n\n- **`enum`**: Lists a specific set of possible strings for classification tasks.\n- **`format`**: Specifies a syntax for the string, such as `date-time`, `date`, `time`.\n\n**For `number` and `integer` values:**\n\n- **`enum`**: Lists a specific set of possible numeric values.\n- **`minimum`**: The minimum inclusive value.\n- **`maximum`**: The maximum inclusive value.\n\n**For `array` values:**\n\n- **`items`**: Defines the schema for all items in the array.\n- **`prefixItems`**: Defines a list of schemas for the first N items, allowing for tuple-like structures.\n- **`minItems`**: The minimum number of items in the array.\n- **`maxItems`**: The maximum number of items in the array.\n## Model support\nThe following models support structured output:\n\n| Model | Structured Outputs |\n|---|---|\n| Gemini 3.1 Pro Preview | ✔️ |\n| Gemini 3 Flash Preview | ✔️ |\n| Gemini 2.5 Pro | ✔️ |\n| Gemini 2.5 Flash | ✔️ |\n| Gemini 2.5 Flash-Lite | ✔️ |\n| Gemini 2.0 Flash | ✔️\\* |\n| Gemini 2.0 Flash-Lite | ✔️\\* |\n\n*\\* Note that Gemini 2.0 requires an explicit `propertyOrdering` list within the JSON input to define the preferred structure. You can find an example in this [cookbook](https:\/\/github.com\/google-gemini\/cookbook\/blob\/main\/examples\/Pdf_structured_outputs_on_invoices_and_forms.ipynb).*\n\n## Structured outputs vs. function calling\nBoth structured outputs and function calling use JSON schemas, but they serve different purposes:\n\n| Feature | Primary Use Case |\n|---|---|\n| **Structured Outputs** | **Formatting the final response to the user.** Use this when you want the model's *answer* to be in a specific format (e.g., extracting data from a document to save to a database). |\n| **Function Calling** | **Taking action during the conversation.** Use this when the model needs to *ask you* to perform a task (e.g., \"get current weather\") before it can provide a final answer. |\n## Best practices\n- **Clear descriptions:** Use the `description` field in your schema to provide clear instructions to the model about what each property represents. This is crucial for guiding the model's output.\n- **Strong typing:** Use specific types (`integer`, `string`, `enum`) whenever possible. If a parameter has a limited set of valid values, use an `enum`.\n- **Prompt engineering:** Clearly state in your prompt what you want the model to do. For example, \"Extract the following information from the text...\" or \"Classify this feedback according to the provided schema...\".\n- **Validation:** While structured output guarantees syntactically correct JSON, it does not guarantee the values are semantically correct. Always validate the final output in your application code before using it.\n- **Error handling:** Implement robust error handling in your application to gracefully manage cases where the model's output, while schema-compliant, may not meet your business logic requirements.\n## Limitations\n- **Schema subset:** Not all features of the JSON Schema specification are supported. The model ignores unsupported properties.\n- **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.\n\nExcept as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https:\/\/creativecommons.org\/licenses\/by\/4.0\/), and code samples are licensed under the [Apache 2.0 License](https:\/\/www.apache.org\/licenses\/LICENSE-2.0). For details, see the [Google Developers Site Policies](https:\/\/developers.google.com\/site-policies). Java is a registered trademark of Oracle and\/or its affiliates.\n\nLast updated 2026-02-26 UTC.","meta_canonical":null}

3. Robots.txt Check

Query:

Response:

4. Spam/Ban Check

Query:

Response:

5. Seen Status Check

ℹ️ Skipped - page is already crawled

📄

INDEXABLE

✅

CRAWLED

3 hours ago

🤖

ROBOTS ALLOWED

Page Info Filters

Filter	Status	Condition	Details
HTTP status	PASS	`download_http_code = 200`	HTTP 200
Age cutoff	PASS	`download_stamp > now() - 6 MONTH`	0 months ago
History drop	PASS	`isNull(history_drop_reason)`	No drop reason
Spam/ban	PASS	`fh_dont_index != 1 AND ml_spam_score = 0`	ml_spam_score=0
Canonical	PASS	`meta_canonical IS NULL OR = '' OR = src_unparsed`	Not set

Page Details

Property	Value
URL	https://ai.google.dev/gemini-api/docs/structured-output
Last Crawled	2026-04-07 05:50:06 (3 hours ago)
First Indexed	2024-08-14 21:09:57 (1 year ago)
HTTP Status Code	200
Meta Title	Structured outputs \| Gemini API \| Google AI for Developers
Meta Description	Learn how to generate structured JSON output with the Gemini API.
Meta Canonical	null
Boilerpipe Text	Skip to main content Gemini API Docs API reference Get API key Cookbook Community Get started Overview Quickstart API keys Libraries Pricing Interactions API Coding agent setup Models All models Gemini 3 Nano Banana Veo Lyria 3 Lyria Real Time Imagen Text-to-speech Embeddings Robotics Core capabilities Text Documents Structured outputs Function calling Long context Agents Overview Deep Research Agent Tools Overview Google Search Google Maps Code execution URL context Computer Use File Search Combine Tools and Function calling Live API Overview Capabilities Tool use Session management Ephemeral tokens Best practices Optimization Overview Batch API Flex inference Priority inference Context caching Guides Open AI compatibility Media resolution Token counting Prompt engineering Resources Release notes Deprecations Rate limits Billing info Migrate to Gen AI SDK API troubleshooting Partner and library integrations Policies Terms of service Available regions Abuse monitoring Feedback information On this page Streaming Structured outputs with tools JSON schema support Type-specific properties Model support Structured outputs vs. function calling Best practices Limitations You can configure Gemini models to generate responses that adhere to a provided JSON Schema. This ensures predictable, type-safe results and simplifies extracting structured data from unstructured text. Using structured outputs is ideal for: Data extraction: Pull specific information like names and dates from text. Structured classification: Classify text into predefined categories. Agentic workflows: Generate structured inputs for tools or APIs. In addition to supporting JSON Schema in the REST API, the Google GenAI SDKs make it easy to define schemas using Pydantic (Python) and Zod (JavaScript). This example demonstrates how to extract structured data from text using basic JSON Schema types like object , array , string , and integer . from google import genai from pydantic import BaseModel , Field from typing import List , Optional class Ingredient ( BaseModel ): name : str = Field ( description = "Name of the ingredient." ) quantity : str = Field ( description = "Quantity of the ingredient, including units." ) class Recipe ( BaseModel ): recipe_name : str = Field ( description = "The name of the recipe." ) prep_time_minutes : Optional [ int ] = Field ( description = "Optional time in minutes to prepare the recipe." ) ingredients : List [ Ingredient ] instructions : List [ str ] client = genai . Client () prompt = """ Please extract the recipe from the following text. The user wants to make delicious chocolate chip cookies. They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda, 1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar, 3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs. For the best part, they'll need 2 cups of semisweet chocolate chips. First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour, baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes. """ response = client . models . generate_content ( model = "gemini-3-flash-preview" , contents = prompt , config = { "response_mime_type" : "application/json" , "response_json_schema" : Recipe . model_json_schema (), }, ) recipe = Recipe . model_validate_json ( response . text ) print ( recipe ) import { GoogleGenAI } from "@google/genai" ; import { z } from "zod" ; import { zodToJsonSchema } from "zod-to-json-schema" ; const ingredientSchema = z . object ({ name : z . string (). describe ( "Name of the ingredient." ), quantity : z . string (). describe ( "Quantity of the ingredient, including units." ), }); const recipeSchema = z . object ({ recipe_name : z . string (). describe ( "The name of the recipe." ), prep_time_minutes : z . number (). optional (). describe ( "Optional time in minutes to prepare the recipe." ), ingredients : z . array ( ingredientSchema ), instructions : z . array ( z . string ()), }); const ai = new GoogleGenAI ({}); const prompt = ` Please extract the recipe from the following text. The user wants to make delicious chocolate chip cookies. They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda, 1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar, 3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs. For the best part, they'll need 2 cups of semisweet chocolate chips. First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour, baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes. ` ; const response = await ai . models . generateContent ({ model : "gemini-3-flash-preview" , contents : prompt , config : { responseMimeType : "application/json" , responseJsonSchema : zodToJsonSchema ( recipeSchema ), }, }); const recipe = recipeSchema . parse ( JSON . parse ( response . text )); console . log ( recipe ); package main import ( "context" "fmt" "log" "google.golang.org/genai" ) func main () { ctx := context . Background () client , err := genai . NewClient ( ctx , nil ) if err != nil { log . Fatal ( err ) } prompt := ` Please extract the recipe from the following text. The user wants to make delicious chocolate chip cookies. They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda, 1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar, 3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs. For the best part, they'll need 2 cups of semisweet chocolate chips. First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour, baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes. ` config := & genai . GenerateContentConfig { ResponseMIMEType : "application/json" , ResponseJsonSchema : map [ string ] any { "type" : "object" , "properties" : map [ string ] any { "recipe_name" : map [ string ] any { "type" : "string" , "description" : "The name of the recipe." , }, "prep_time_minutes" : map [ string ] any { "type" : "integer" , "description" : "Optional time in minutes to prepare the recipe." , }, "ingredients" : map [ string ] any { "type" : "array" , "items" : map [ string ] any { "type" : "object" , "properties" : map [ string ] any { "name" : map [ string ] any { "type" : "string" , "description" : "Name of the ingredient." , }, "quantity" : map [ string ] any { "type" : "string" , "description" : "Quantity of the ingredient, including units." , }, }, "required" : [] string { "name" , "quantity" }, }, }, "instructions" : map [ string ] any { "type" : "array" , "items" : map [ string ] any { "type" : "string" }, }, }, "required" : [] string { "recipe_name" , "ingredients" , "instructions" }, }, } result , err := client . Models . GenerateContent ( ctx , "gemini-3-flash-preview" , genai . Text ( prompt ), config , ) if err != nil { log . Fatal ( err ) } fmt . Println ( result . Text ()) } curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY " \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "contents": [{ "parts":[ { "text": "Please extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,\n3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they will need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes." } ] }], "generationConfig": { "responseMimeType": "application/json", "responseJsonSchema": { "type": "object", "properties": { "recipe_name": { "type": "string", "description": "The name of the recipe." }, "prep_time_minutes": { "type": "integer", "description": "Optional time in minutes to prepare the recipe." }, "ingredients": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the ingredient."}, "quantity": { "type": "string", "description": "Quantity of the ingredient, including units."} }, "required": ["name", "quantity"] } }, "instructions": { "type": "array", "items": { "type": "string" } } }, "required": ["recipe_name", "ingredients", "instructions"] } } }' Example Response: { "recipe_name" : "Delicious Chocolate Chip Cookies" , "ingredients" : [ { "name" : "all-purpose flour" , "quantity" : "2 and 1/4 cups" }, { "name" : "baking soda" , "quantity" : "1 teaspoon" }, { "name" : "salt" , "quantity" : "1 teaspoon" }, { "name" : "unsalted butter (softened)" , "quantity" : "1 cup" }, { "name" : "granulated sugar" , "quantity" : "3/4 cup" }, { "name" : "packed brown sugar" , "quantity" : "3/4 cup" }, { "name" : "vanilla extract" , "quantity" : "1 teaspoon" }, { "name" : "large eggs" , "quantity" : "2" }, { "name" : "semisweet chocolate chips" , "quantity" : "2 cups" } ], "instructions" : [ "Preheat the oven to 375°F (190°C)." , "In a small bowl, whisk together the flour, baking soda, and salt." , "In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy." , "Beat in the vanilla and eggs, one at a time." , "Gradually beat in the dry ingredients until just combined." , "Stir in the chocolate chips." , "Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes." ] } Streaming You can stream structured outputs, which allows you to start processing the response as it's being generated, without having to wait for the entire output to be complete. This can improve the perceived performance of your application. The streamed chunks will be valid partial JSON strings, which can be concatenated to form the final, complete JSON object. from google import genai from pydantic import BaseModel , Field from typing import Literal class Feedback ( BaseModel ): sentiment : Literal [ "positive" , "neutral" , "negative" ] summary : str client = genai . Client () prompt = "The new UI is incredibly intuitive and visually appealing. Great job. Add a very long summary to test streaming!" response_stream = client . models . generate_content_stream ( model = "gemini-3-flash-preview" , contents = prompt , config = { "response_mime_type" : "application/json" , "response_json_schema" : Feedback . model_json_schema (), }, ) for chunk in response_stream : print ( chunk . candidates [ 0 ] . content . parts [ 0 ] . text ) import { GoogleGenAI } from "@google/genai" ; import { z } from "zod" ; import { zodToJsonSchema } from "zod-to-json-schema" ; const ai = new GoogleGenAI ({}); const prompt = "The new UI is incredibly intuitive and visually appealing. Great job! Add a very long summary to test streaming!" ; const feedbackSchema = z . object ({ sentiment : z . enum ([ "positive" , "neutral" , "negative" ]), summary : z . string (), }); const stream = await ai . models . generateContentStream ({ model : "gemini-3-flash-preview" , contents : prompt , config : { responseMimeType : "application/json" , responseJsonSchema : zodToJsonSchema ( feedbackSchema ), }, }); for await ( const chunk of stream ) { console . log ( chunk . candidates [ 0 ]. content . parts [ 0 ]. text ) } Structured outputs with tools Gemini 3 lets you combine Structured Outputs with built-in tools, including Grounding with Google Search , URL Context , Code Execution , File Search , and Function Calling . from google import genai from pydantic import BaseModel , Field from typing import List class MatchResult ( BaseModel ): winner : str = Field ( description = "The name of the winner." ) final_match_score : str = Field ( description = "The final match score." ) scorers : List [ str ] = Field ( description = "The name of the scorer." ) client = genai . Client () response = client . models . generate_content ( model = "gemini-3.1-pro-preview" , contents = "Search for all details for the latest Euro." , config = { "tools" : [ { "google_search" : {}}, { "url_context" : {}} ], "response_mime_type" : "application/json" , "response_json_schema" : MatchResult . model_json_schema (), }, ) result = MatchResult . model_validate_json ( response . text ) print ( result ) import { GoogleGenAI } from "@google/genai" ; import { z } from "zod" ; import { zodToJsonSchema } from "zod-to-json-schema" ; const ai = new GoogleGenAI ({}); const matchSchema = z . object ({ winner : z . string (). describe ( "The name of the winner." ), final_match_score : z . string (). describe ( "The final score." ), scorers : z . array ( z . string ()). describe ( "The name of the scorer." ) }); async function run () { const response = await ai . models . generateContent ({ model : "gemini-3.1-pro-preview" , contents : "Search for all details for the latest Euro." , config : { tools : [ { googleSearch : {} }, { urlContext : {} } ], responseMimeType : "application/json" , responseJsonSchema : zodToJsonSchema ( matchSchema ), }, }); const match = matchSchema . parse ( JSON . parse ( response . text )); console . log ( match ); } run (); curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY " \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "contents": [{ "parts": [{"text": "Search for all details for the latest Euro."}] }], "tools": [ {"googleSearch": {}}, {"urlContext": {}} ], "generationConfig": { "responseMimeType": "application/json", "responseJsonSchema": { "type": "object", "properties": { "winner": {"type": "string", "description": "The name of the winner."}, "final_match_score": {"type": "string", "description": "The final score."}, "scorers": { "type": "array", "items": {"type": "string"}, "description": "The name of the scorer." } }, "required": ["winner", "final_match_score", "scorers"] } } }' JSON schema support To generate a JSON object, set the response_mime_type in the generation configuration to application/json and provide a response_json_schema . The schema must be a valid JSON Schema that describes the desired output format. The model will then generate a response that is a syntactically valid JSON string matching the provided schema. When using structured outputs, the model will produce outputs in the same order as the keys in the schema. Gemini's structured output mode supports a subset of the JSON Schema specification. The following values of type are supported: string : For text. number : For floating-point numbers. integer : For whole numbers. boolean : For true/false values. object : For structured data with key-value pairs. array : For lists of items. null : To allow a property to be null, include "null" in the type array (e.g., {"type": ["string", "null"]} ). These descriptive properties help guide the model: title : A short description of a property. description : A longer and more detailed description of a property. Type-specific properties For object values: properties : An object where each key is a property name and each value is a schema for that property. required : An array of strings, listing which properties are mandatory. additionalProperties : Controls whether properties not listed in properties are allowed. Can be a boolean or a schema. For string values: enum : Lists a specific set of possible strings for classification tasks. format : Specifies a syntax for the string, such as date-time , date , time . For number and integer values: enum : Lists a specific set of possible numeric values. minimum : The minimum inclusive value. maximum : The maximum inclusive value. For array values: items : Defines the schema for all items in the array. prefixItems : Defines a list of schemas for the first N items, allowing for tuple-like structures. minItems : The minimum number of items in the array. maxItems : The maximum number of items in the array. Model support The following models support structured output: Model Structured Outputs Gemini 3.1 Pro Preview ✔️ Gemini 3 Flash Preview ✔️ Gemini 2.5 Pro ✔️ Gemini 2.5 Flash ✔️ Gemini 2.5 Flash-Lite ✔️ Gemini 2.0 Flash ✔️* Gemini 2.0 Flash-Lite ✔️* * Note that Gemini 2.0 requires an explicit propertyOrdering list within the JSON input to define the preferred structure. You can find an example in this cookbook . Structured outputs vs. function calling Both structured outputs and function calling use JSON schemas, but they serve different purposes: Feature Primary Use Case Structured Outputs Formatting the final response to the user. Use this when you want the model's answer to be in a specific format (e.g., extracting data from a document to save to a database). Function Calling Taking action during the conversation. Use this when the model needs to ask you to perform a task (e.g., "get current weather") before it can provide a final answer. Best practices Clear descriptions: Use the description field in your schema to provide clear instructions to the model about what each property represents. This is crucial for guiding the model's output. Strong typing: Use specific types ( integer , string , enum ) whenever possible. If a parameter has a limited set of valid values, use an enum . Prompt engineering: Clearly state in your prompt what you want the model to do. For example, "Extract the following information from the text..." or "Classify this feedback according to the provided schema...". Validation: While structured output guarantees syntactically correct JSON, it does not guarantee the values are semantically correct. Always validate the final output in your application code before using it. Error handling: Implement robust error handling in your application to gracefully manage cases where the model's output, while schema-compliant, may not meet your business logic requirements. Limitations Schema subset: Not all features of the JSON Schema specification are supported. The model ignores unsupported properties. 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. Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License , and code samples are licensed under the Apache 2.0 License . For details, see the Google Developers Site Policies . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2026-02-26 UTC. [[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2026-02-26 UTC."],[],[]]
Markdown	[Skip to main content](https://ai.google.dev/gemini-api/docs/structured-output#main-content) [![Gemini API](https://ai.google.dev/_static/googledevai/images/gemini-api-logo.svg)](https://ai.google.dev/) - [English](https://ai.google.dev/gemini-api/docs/structured-output) - [Deutsch](https://ai.google.dev/gemini-api/docs/structured-output?hl=de) - [Español – América Latina](https://ai.google.dev/gemini-api/docs/structured-output?hl=es-419) - [Français](https://ai.google.dev/gemini-api/docs/structured-output?hl=fr) - [Indonesia](https://ai.google.dev/gemini-api/docs/structured-output?hl=id) - [Italiano](https://ai.google.dev/gemini-api/docs/structured-output?hl=it) - [Polski](https://ai.google.dev/gemini-api/docs/structured-output?hl=pl) - [Português – Brasil](https://ai.google.dev/gemini-api/docs/structured-output?hl=pt-br) - [Shqip](https://ai.google.dev/gemini-api/docs/structured-output?hl=sq) - [Tiếng Việt](https://ai.google.dev/gemini-api/docs/structured-output?hl=vi) - [Türkçe](https://ai.google.dev/gemini-api/docs/structured-output?hl=tr) - [Русский](https://ai.google.dev/gemini-api/docs/structured-output?hl=ru) - [עברית](https://ai.google.dev/gemini-api/docs/structured-output?hl=he) - [العربيّة](https://ai.google.dev/gemini-api/docs/structured-output?hl=ar) - [فارسی](https://ai.google.dev/gemini-api/docs/structured-output?hl=fa) - [हिंदी](https://ai.google.dev/gemini-api/docs/structured-output?hl=hi) - [বাংলা](https://ai.google.dev/gemini-api/docs/structured-output?hl=bn) - [ภาษาไทย](https://ai.google.dev/gemini-api/docs/structured-output?hl=th) - [中文 – 简体](https://ai.google.dev/gemini-api/docs/structured-output?hl=zh-cn) - [中文 – 繁體](https://ai.google.dev/gemini-api/docs/structured-output?hl=zh-tw) - [日本語](https://ai.google.dev/gemini-api/docs/structured-output?hl=ja) - [한국어](https://ai.google.dev/gemini-api/docs/structured-output?hl=ko) [Get API key](https://aistudio.google.com/apikey) [Cookbook](https://github.com/google-gemini/cookbook) [Community](https://discuss.ai.google.dev/c/gemini-api/) [Sign in](https://ai.google.dev/_d/signin?continue=https%3A%2F%2Fai.google.dev%2Fgemini-api%2Fdocs%2Fstructured-output%3Fexample%3Drecipe&prompt=select_account) [Docs](https://ai.google.dev/gemini-api/docs) [API reference](https://ai.google.dev/api) More [![Gemini API](https://ai.google.dev/_static/googledevai/images/gemini-api-logo.svg)](https://ai.google.dev/) - [Gemini API](https://ai.google.dev/gemini-api/docs) - [Docs](https://ai.google.dev/gemini-api/docs) - [API reference](https://ai.google.dev/api) - [Get API key](https://aistudio.google.com/apikey) - [Cookbook](https://github.com/google-gemini/cookbook) - [Community](https://discuss.ai.google.dev/c/gemini-api/) - Get started - [Overview](https://ai.google.dev/gemini-api/docs) - [Quickstart](https://ai.google.dev/gemini-api/docs/quickstart) - [API keys](https://ai.google.dev/gemini-api/docs/api-key) - [Libraries](https://ai.google.dev/gemini-api/docs/libraries) - [Pricing](https://ai.google.dev/gemini-api/docs/pricing) - [Interactions API](https://ai.google.dev/gemini-api/docs/interactions) - [Coding agent setup](https://ai.google.dev/gemini-api/docs/coding-agents) - Models - [All models](https://ai.google.dev/gemini-api/docs/models) - [Gemini 3](https://ai.google.dev/gemini-api/docs/gemini-3) - [Nano Banana](https://ai.google.dev/gemini-api/docs/image-generation) - [Veo](https://ai.google.dev/gemini-api/docs/video) - [Lyria 3](https://ai.google.dev/gemini-api/docs/music-generation) - [Lyria Real Time](https://ai.google.dev/gemini-api/docs/realtime-music-generation) - [Imagen](https://ai.google.dev/gemini-api/docs/imagen) - [Text-to-speech](https://ai.google.dev/gemini-api/docs/speech-generation) - [Embeddings](https://ai.google.dev/gemini-api/docs/embeddings) - [Robotics](https://ai.google.dev/gemini-api/docs/robotics-overview) - Core capabilities - [Text](https://ai.google.dev/gemini-api/docs/text-generation) - Image - [Image generation 🍌](https://ai.google.dev/gemini-api/docs/image-generation) - [Image understanding](https://ai.google.dev/gemini-api/docs/image-understanding) - Video - [Video generation](https://ai.google.dev/gemini-api/docs/video) - [Video understanding](https://ai.google.dev/gemini-api/docs/video-understanding) - [Documents](https://ai.google.dev/gemini-api/docs/document-processing) - Speech and audio - [Speech generation](https://ai.google.dev/gemini-api/docs/speech-generation) - [Audio understanding](https://ai.google.dev/gemini-api/docs/audio) - Thinking - [Thinking](https://ai.google.dev/gemini-api/docs/thinking) - [Thought signatures](https://ai.google.dev/gemini-api/docs/thought-signatures) - [Structured outputs](https://ai.google.dev/gemini-api/docs/structured-output) - [Function calling](https://ai.google.dev/gemini-api/docs/function-calling) - [Long context](https://ai.google.dev/gemini-api/docs/long-context) - Agents - [Overview](https://ai.google.dev/gemini-api/docs/agents) - [Deep Research Agent](https://ai.google.dev/gemini-api/docs/deep-research) - Tools - [Overview](https://ai.google.dev/gemini-api/docs/tools) - [Google Search](https://ai.google.dev/gemini-api/docs/google-search) - [Google Maps](https://ai.google.dev/gemini-api/docs/maps-grounding) - [Code execution](https://ai.google.dev/gemini-api/docs/code-execution) - [URL context](https://ai.google.dev/gemini-api/docs/url-context) - [Computer Use](https://ai.google.dev/gemini-api/docs/computer-use) - [File Search](https://ai.google.dev/gemini-api/docs/file-search) - [Combine Tools and Function calling](https://ai.google.dev/gemini-api/docs/tool-combination) - Live API - [Overview](https://ai.google.dev/gemini-api/docs/live-api) - Get started - [Get started using the GenAI SDK](https://ai.google.dev/gemini-api/docs/live-api/get-started-sdk) - [Get started using raw WebSockets](https://ai.google.dev/gemini-api/docs/live-api/get-started-websocket) - [Capabilities](https://ai.google.dev/gemini-api/docs/live-api/capabilities) - [Tool use](https://ai.google.dev/gemini-api/docs/live-api/tools) - [Session management](https://ai.google.dev/gemini-api/docs/live-api/session-management) - [Ephemeral tokens](https://ai.google.dev/gemini-api/docs/live-api/ephemeral-tokens) - [Best practices](https://ai.google.dev/gemini-api/docs/live-api/best-practices) - Optimization - [Overview](https://ai.google.dev/gemini-api/docs/optimization) - [Batch API](https://ai.google.dev/gemini-api/docs/batch-api) - [Flex inference](https://ai.google.dev/gemini-api/docs/flex-inference) - [Priority inference](https://ai.google.dev/gemini-api/docs/priority-inference) - [Context caching](https://ai.google.dev/gemini-api/docs/caching) - Guides - File input - [Input methods](https://ai.google.dev/gemini-api/docs/file-input-methods) - [Files API](https://ai.google.dev/gemini-api/docs/files) - [Open AI compatibility](https://ai.google.dev/gemini-api/docs/openai) - [Media resolution](https://ai.google.dev/gemini-api/docs/media-resolution) - [Token counting](https://ai.google.dev/gemini-api/docs/tokens) - [Prompt engineering](https://ai.google.dev/gemini-api/docs/prompting-strategies) - Logs and datasets - [Get started with logs](https://ai.google.dev/gemini-api/docs/logs-datasets) - [Data logging and sharing](https://ai.google.dev/gemini-api/docs/logs-policy) - Safety - [Safety settings](https://ai.google.dev/gemini-api/docs/safety-settings) - [Safety guidance](https://ai.google.dev/gemini-api/docs/safety-guidance) - Frameworks - [LangChain & LangGraph](https://ai.google.dev/gemini-api/docs/langgraph-example) - [CrewAI](https://ai.google.dev/gemini-api/docs/crewai-example) - [LlamaIndex](https://ai.google.dev/gemini-api/docs/llama-index) - [Vercel AI SDK](https://ai.google.dev/gemini-api/docs/vercel-ai-sdk-example) - [Temporal](https://ai.google.dev/gemini-api/docs/temporal-example) - Resources - [Release notes](https://ai.google.dev/gemini-api/docs/changelog) - [Deprecations](https://ai.google.dev/gemini-api/docs/deprecations) - [Rate limits](https://ai.google.dev/gemini-api/docs/rate-limits) - [Billing info](https://ai.google.dev/gemini-api/docs/billing) - [Migrate to Gen AI SDK](https://ai.google.dev/gemini-api/docs/migrate) - [API troubleshooting](https://ai.google.dev/gemini-api/docs/troubleshooting) - [Partner and library integrations](https://ai.google.dev/gemini-api/docs/partner-integration) - Google AI Studio - [Quickstart](https://ai.google.dev/gemini-api/docs/ai-studio-quickstart) - [Vibe code in Build mode](https://ai.google.dev/gemini-api/docs/aistudio-build-mode) - [Developing Full-Stack Apps](https://ai.google.dev/gemini-api/docs/aistudio-fullstack) - [Troubleshooting](https://ai.google.dev/gemini-api/docs/troubleshoot-ai-studio) - [Access for Workspace users](https://ai.google.dev/gemini-api/docs/workspace) - Google Cloud Platform - [VertexAI Gemini API](https://ai.google.dev/gemini-api/docs/migrate-to-cloud) - [OAuth authentication](https://ai.google.dev/gemini-api/docs/oauth) - Policies - [Terms of service](https://ai.google.dev/gemini-api/terms) - [Available regions](https://ai.google.dev/gemini-api/docs/available-regions) - [Abuse monitoring](https://ai.google.dev/gemini-api/docs/usage-policies) - [Feedback information](https://ai.google.dev/gemini-api/docs/feedback-policies) - On this page - [Streaming](https://ai.google.dev/gemini-api/docs/structured-output#streaming) - [Structured outputs with tools](https://ai.google.dev/gemini-api/docs/structured-output#structured_outputs_with_tools) - [JSON schema support](https://ai.google.dev/gemini-api/docs/structured-output#json_schema_support) - [Type-specific properties](https://ai.google.dev/gemini-api/docs/structured-output#type-specific_properties) - [Model support](https://ai.google.dev/gemini-api/docs/structured-output#model_support) - [Structured outputs vs. function calling](https://ai.google.dev/gemini-api/docs/structured-output#structured_outputs_vs_function_calling) - [Best practices](https://ai.google.dev/gemini-api/docs/structured-output#best_practices) - [Limitations](https://ai.google.dev/gemini-api/docs/structured-output#limitations) Try the new high-speed, cost-effective [Veo 3.1 Lite](https://ai.google.dev/gemini-api/docs/models/veo-3.1-lite-generate-preview) model for video generation at scale. - [Home](https://ai.google.dev/) - [Gemini API](https://ai.google.dev/gemini-api) - [Docs](https://ai.google.dev/gemini-api/docs) Was this helpful? Send feedback # Structured outputs - On this page - [Streaming](https://ai.google.dev/gemini-api/docs/structured-output#streaming) - [Structured outputs with tools](https://ai.google.dev/gemini-api/docs/structured-output#structured_outputs_with_tools) - [JSON schema support](https://ai.google.dev/gemini-api/docs/structured-output#json_schema_support) - [Type-specific properties](https://ai.google.dev/gemini-api/docs/structured-output#type-specific_properties) - [Model support](https://ai.google.dev/gemini-api/docs/structured-output#model_support) - [Structured outputs vs. function calling](https://ai.google.dev/gemini-api/docs/structured-output#structured_outputs_vs_function_calling) - [Best practices](https://ai.google.dev/gemini-api/docs/structured-output#best_practices) - [Limitations](https://ai.google.dev/gemini-api/docs/structured-output#limitations) You can configure Gemini models to generate responses that adhere to a provided JSON Schema. This ensures predictable, type-safe results and simplifies extracting structured data from unstructured text. Using structured outputs is ideal for: - Data extraction: Pull specific information like names and dates from text. - Structured classification: Classify text into predefined categories. - Agentic workflows: Generate structured inputs for tools or APIs. In addition to supporting JSON Schema in the REST API, the Google GenAI SDKs make it easy to define schemas using [Pydantic](https://docs.pydantic.dev/latest/) (Python) and [Zod](https://zod.dev/) (JavaScript). Recipe Extractor Content Moderation Recursive Structures This example demonstrates how to extract structured data from text using basic JSON Schema types like `object`, `array`, `string`, and `integer`. [Python](https://ai.google.dev/gemini-api/docs/structured-output#python) [JavaScript](https://ai.google.dev/gemini-api/docs/structured-output#javascript) [Go](https://ai.google.dev/gemini-api/docs/structured-output#go) [REST](https://ai.google.dev/gemini-api/docs/structured-output#rest) More ``` from google import genai from pydantic import BaseModel, Field from typing import List, Optional class Ingredient(BaseModel): name: str = Field(description="Name of the ingredient.") quantity: str = Field(description="Quantity of the ingredient, including units.") class Recipe(BaseModel): recipe_name: str = Field(description="The name of the recipe.") prep_time_minutes: Optional[int] = Field(description="Optional time in minutes to prepare the recipe.") ingredients: List[Ingredient] instructions: List[str] client = genai.Client() prompt = """ Please extract the recipe from the following text. The user wants to make delicious chocolate chip cookies. They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda, 1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar, 3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs. For the best part, they'll need 2 cups of semisweet chocolate chips. First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour, baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes. """ response = client.models.generate_content( model="gemini-3-flash-preview", contents=prompt, config={ "response_mime_type": "application/json", "response_json_schema": Recipe.model_json_schema(), }, ) recipe = Recipe.model_validate_json(response.text) print(recipe) ``` ``` import { GoogleGenAI } from "@google/genai"; import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema"; const ingredientSchema = z.object({ name: z.string().describe("Name of the ingredient."), quantity: z.string().describe("Quantity of the ingredient, including units."), }); const recipeSchema = z.object({ recipe_name: z.string().describe("The name of the recipe."), prep_time_minutes: z.number().optional().describe("Optional time in minutes to prepare the recipe."), ingredients: z.array(ingredientSchema), instructions: z.array(z.string()), }); const ai = new GoogleGenAI({}); const prompt = ` Please extract the recipe from the following text. The user wants to make delicious chocolate chip cookies. They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda, 1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar, 3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs. For the best part, they'll need 2 cups of semisweet chocolate chips. First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour, baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes. `; const response = await ai.models.generateContent({ model: "gemini-3-flash-preview", contents: prompt, config: { responseMimeType: "application/json", responseJsonSchema: zodToJsonSchema(recipeSchema), }, }); const recipe = recipeSchema.parse(JSON.parse(response.text)); console.log(recipe); ``` ``` package main import ( "context" "fmt" "log" "google.golang.org/genai" ) func main() { ctx := context.Background() client, err := genai.NewClient(ctx, nil) if err != nil { log.Fatal(err) } prompt := ` Please extract the recipe from the following text. The user wants to make delicious chocolate chip cookies. They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda, 1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar, 3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs. For the best part, they'll need 2 cups of semisweet chocolate chips. First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour, baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes. ` config := &genai.GenerateContentConfig{ ResponseMIMEType: "application/json", ResponseJsonSchema: map[string]any{ "type": "object", "properties": map[string]any{ "recipe_name": map[string]any{ "type": "string", "description": "The name of the recipe.", }, "prep_time_minutes": map[string]any{ "type": "integer", "description": "Optional time in minutes to prepare the recipe.", }, "ingredients": map[string]any{ "type": "array", "items": map[string]any{ "type": "object", "properties": map[string]any{ "name": map[string]any{ "type": "string", "description": "Name of the ingredient.", }, "quantity": map[string]any{ "type": "string", "description": "Quantity of the ingredient, including units.", }, }, "required": []string{"name", "quantity"}, }, }, "instructions": map[string]any{ "type": "array", "items": map[string]any{"type": "string"}, }, }, "required": []string{"recipe_name", "ingredients", "instructions"}, }, } result, err := client.Models.GenerateContent( ctx, "gemini-3-flash-preview", genai.Text(prompt), config, ) if err != nil { log.Fatal(err) } fmt.Println(result.Text()) } ``` ``` curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "contents": [{ "parts":[ { "text": "Please extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,\n3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they will need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes." } ] }], "generationConfig": { "responseMimeType": "application/json", "responseJsonSchema": { "type": "object", "properties": { "recipe_name": { "type": "string", "description": "The name of the recipe." }, "prep_time_minutes": { "type": "integer", "description": "Optional time in minutes to prepare the recipe." }, "ingredients": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the ingredient."}, "quantity": { "type": "string", "description": "Quantity of the ingredient, including units."} }, "required": ["name", "quantity"] } }, "instructions": { "type": "array", "items": { "type": "string" } } }, "required": ["recipe_name", "ingredients", "instructions"] } } }' ``` Example Response: ``` { "recipe_name": "Delicious Chocolate Chip Cookies", "ingredients": [ { "name": "all-purpose flour", "quantity": "2 and 1/4 cups" }, { "name": "baking soda", "quantity": "1 teaspoon" }, { "name": "salt", "quantity": "1 teaspoon" }, { "name": "unsalted butter (softened)", "quantity": "1 cup" }, { "name": "granulated sugar", "quantity": "3/4 cup" }, { "name": "packed brown sugar", "quantity": "3/4 cup" }, { "name": "vanilla extract", "quantity": "1 teaspoon" }, { "name": "large eggs", "quantity": "2" }, { "name": "semisweet chocolate chips", "quantity": "2 cups" } ], "instructions": [ "Preheat the oven to 375°F (190°C).", "In a small bowl, whisk together the flour, baking soda, and salt.", "In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy.", "Beat in the vanilla and eggs, one at a time.", "Gradually beat in the dry ingredients until just combined.", "Stir in the chocolate chips.", "Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes." ] } ``` ## Streaming You can stream structured outputs, which allows you to start processing the response as it's being generated, without having to wait for the entire output to be complete. This can improve the perceived performance of your application. The streamed chunks will be valid partial JSON strings, which can be concatenated to form the final, complete JSON object. [Python](https://ai.google.dev/gemini-api/docs/structured-output#python) [JavaScript](https://ai.google.dev/gemini-api/docs/structured-output#javascript) More ``` from google import genai from pydantic import BaseModel, Field from typing import Literal class Feedback(BaseModel): sentiment: Literal["positive", "neutral", "negative"] summary: str client = genai.Client() prompt = "The new UI is incredibly intuitive and visually appealing. Great job. Add a very long summary to test streaming!" response_stream = client.models.generate_content_stream( model="gemini-3-flash-preview", contents=prompt, config={ "response_mime_type": "application/json", "response_json_schema": Feedback.model_json_schema(), }, ) for chunk in response_stream: print(chunk.candidates[0].content.parts[0].text) ``` ``` import { GoogleGenAI } from "@google/genai"; import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema"; const ai = new GoogleGenAI({}); const prompt = "The new UI is incredibly intuitive and visually appealing. Great job! Add a very long summary to test streaming!"; const feedbackSchema = z.object({ sentiment: z.enum(["positive", "neutral", "negative"]), summary: z.string(), }); const stream = await ai.models.generateContentStream({ model: "gemini-3-flash-preview", contents: prompt, config: { responseMimeType: "application/json", responseJsonSchema: zodToJsonSchema(feedbackSchema), }, }); for await (const chunk of stream) { console.log(chunk.candidates[0].content.parts[0].text) } ``` ## Structured outputs with tools Preview: This feature is available only to Gemini 3 series models, `gemini-3.1-pro-preview` and `gemini-3-flash-preview`. Gemini 3 lets you combine Structured Outputs with built-in tools, including [Grounding with Google Search](https://ai.google.dev/gemini-api/docs/google-search), [URL Context](https://ai.google.dev/gemini-api/docs/url-context), [Code Execution](https://ai.google.dev/gemini-api/docs/code-execution), [File Search](https://ai.google.dev/gemini-api/docs/file-search#structured-output), and [Function Calling](https://ai.google.dev/gemini-api/docs/function-calling). [Python](https://ai.google.dev/gemini-api/docs/structured-output#python) [JavaScript](https://ai.google.dev/gemini-api/docs/structured-output#javascript) [REST](https://ai.google.dev/gemini-api/docs/structured-output#rest) More ``` from google import genai from pydantic import BaseModel, Field from typing import List class MatchResult(BaseModel): winner: str = Field(description="The name of the winner.") final_match_score: str = Field(description="The final match score.") scorers: List[str] = Field(description="The name of the scorer.") client = genai.Client() response = client.models.generate_content( model="gemini-3.1-pro-preview", contents="Search for all details for the latest Euro.", config={ "tools": [ {"google_search": {}}, {"url_context": {}} ], "response_mime_type": "application/json", "response_json_schema": MatchResult.model_json_schema(), }, ) result = MatchResult.model_validate_json(response.text) print(result) ``` ``` import { GoogleGenAI } from "@google/genai"; import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema"; const ai = new GoogleGenAI({}); const matchSchema = z.object({ winner: z.string().describe("The name of the winner."), final_match_score: z.string().describe("The final score."), scorers: z.array(z.string()).describe("The name of the scorer.") }); async function run() { const response = await ai.models.generateContent({ model: "gemini-3.1-pro-preview", contents: "Search for all details for the latest Euro.", config: { tools: [ { googleSearch: {} }, { urlContext: {} } ], responseMimeType: "application/json", responseJsonSchema: zodToJsonSchema(matchSchema), }, }); const match = matchSchema.parse(JSON.parse(response.text)); console.log(match); } run(); ``` ``` curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "contents": [{ "parts": [{"text": "Search for all details for the latest Euro."}] }], "tools": [ {"googleSearch": {}}, {"urlContext": {}} ], "generationConfig": { "responseMimeType": "application/json", "responseJsonSchema": { "type": "object", "properties": { "winner": {"type": "string", "description": "The name of the winner."}, "final_match_score": {"type": "string", "description": "The final score."}, "scorers": { "type": "array", "items": {"type": "string"}, "description": "The name of the scorer." } }, "required": ["winner", "final_match_score", "scorers"] } } }' ``` ## JSON schema support To generate a JSON object, set the `response_mime_type` in the generation configuration to `application/json` and provide a `response_json_schema`. The schema must be a valid [JSON Schema](https://json-schema.org/) that describes the desired output format. The model will then generate a response that is a syntactically valid JSON string matching the provided schema. When using structured outputs, the model will produce outputs in the same order as the keys in the schema. Gemini's structured output mode supports a subset of the [JSON Schema](https://json-schema.org/) specification. The following values of `type` are supported: - `string`: For text. - `number`: For floating-point numbers. - `integer`: For whole numbers. - `boolean`: For true/false values. - `object`: For structured data with key-value pairs. - `array`: For lists of items. - `null`: To allow a property to be null, include `"null"` in the type array (e.g., `{"type": ["string", "null"]}`). These descriptive properties help guide the model: - `title`: A short description of a property. - `description`: A longer and more detailed description of a property. ### Type-specific properties For `object` values: - `properties`: An object where each key is a property name and each value is a schema for that property. - `required`: An array of strings, listing which properties are mandatory. - `additionalProperties`: Controls whether properties not listed in `properties` are allowed. Can be a boolean or a schema. For `string` values: - `enum`: Lists a specific set of possible strings for classification tasks. - `format`: Specifies a syntax for the string, such as `date-time`, `date`, `time`. For `number` and `integer` values: - `enum`: Lists a specific set of possible numeric values. - `minimum`: The minimum inclusive value. - `maximum`: The maximum inclusive value. For `array` values: - `items`: Defines the schema for all items in the array. - `prefixItems`: Defines a list of schemas for the first N items, allowing for tuple-like structures. - `minItems`: The minimum number of items in the array. - `maxItems`: The maximum number of items in the array. ## Model support The following models support structured output: \| Model \| Structured Outputs \| \|---\|---\| \| Gemini 3.1 Pro Preview \| ✔️ \| \| Gemini 3 Flash Preview \| ✔️ \| \| Gemini 2.5 Pro \| ✔️ \| \| Gemini 2.5 Flash \| ✔️ \| \| Gemini 2.5 Flash-Lite \| ✔️ \| \| Gemini 2.0 Flash \| ✔️\* \| \| Gemini 2.0 Flash-Lite \| ✔️\* \| \ Note that Gemini 2.0 requires an explicit `propertyOrdering` list within the JSON input to define the preferred structure. You can find an example in this [cookbook](https://github.com/google-gemini/cookbook/blob/main/examples/Pdf_structured_outputs_on_invoices_and_forms.ipynb).* ## Structured outputs vs. function calling Both structured outputs and function calling use JSON schemas, but they serve different purposes: \| Feature \| Primary Use Case \| \|---\|---\| \| Structured Outputs \| Formatting the final response to the user. Use this when you want the model's answer to be in a specific format (e.g., extracting data from a document to save to a database). \| \| Function Calling \| Taking action during the conversation. Use this when the model needs to ask you to perform a task (e.g., "get current weather") before it can provide a final answer. \| ## Best practices - Clear descriptions: Use the `description` field in your schema to provide clear instructions to the model about what each property represents. This is crucial for guiding the model's output. - Strong typing: Use specific types (`integer`, `string`, `enum`) whenever possible. If a parameter has a limited set of valid values, use an `enum`. - Prompt engineering: Clearly state in your prompt what you want the model to do. For example, "Extract the following information from the text..." or "Classify this feedback according to the provided schema...". - Validation: While structured output guarantees syntactically correct JSON, it does not guarantee the values are semantically correct. Always validate the final output in your application code before using it. - Error handling: Implement robust error handling in your application to gracefully manage cases where the model's output, while schema-compliant, may not meet your business logic requirements. ## Limitations - Schema subset: Not all features of the JSON Schema specification are supported. The model ignores unsupported properties. - 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. Was this helpful? Send feedback Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/), and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0). For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its affiliates. Last updated 2026-02-26 UTC. - [Terms](https://policies.google.com/terms) - [Privacy](https://policies.google.com/privacy) - [Manage cookies](https://ai.google.dev/gemini-api/docs/structured-output) - [English](https://ai.google.dev/gemini-api/docs/structured-output) - [Deutsch](https://ai.google.dev/gemini-api/docs/structured-output?hl=de) - [Español – América Latina](https://ai.google.dev/gemini-api/docs/structured-output?hl=es-419) - [Français](https://ai.google.dev/gemini-api/docs/structured-output?hl=fr) - [Indonesia](https://ai.google.dev/gemini-api/docs/structured-output?hl=id) - [Italiano](https://ai.google.dev/gemini-api/docs/structured-output?hl=it) - [Polski](https://ai.google.dev/gemini-api/docs/structured-output?hl=pl) - [Português – Brasil](https://ai.google.dev/gemini-api/docs/structured-output?hl=pt-br) - [Shqip](https://ai.google.dev/gemini-api/docs/structured-output?hl=sq) - [Tiếng Việt](https://ai.google.dev/gemini-api/docs/structured-output?hl=vi) - [Türkçe](https://ai.google.dev/gemini-api/docs/structured-output?hl=tr) - [Русский](https://ai.google.dev/gemini-api/docs/structured-output?hl=ru) - [עברית](https://ai.google.dev/gemini-api/docs/structured-output?hl=he) - [العربيّة](https://ai.google.dev/gemini-api/docs/structured-output?hl=ar) - [فارسی](https://ai.google.dev/gemini-api/docs/structured-output?hl=fa) - [हिंदी](https://ai.google.dev/gemini-api/docs/structured-output?hl=hi) - [বাংলা](https://ai.google.dev/gemini-api/docs/structured-output?hl=bn) - [ภาษาไทย](https://ai.google.dev/gemini-api/docs/structured-output?hl=th) - [中文 – 简体](https://ai.google.dev/gemini-api/docs/structured-output?hl=zh-cn) - [中文 – 繁體](https://ai.google.dev/gemini-api/docs/structured-output?hl=zh-tw) - [日本語](https://ai.google.dev/gemini-api/docs/structured-output?hl=ja) - [한국어](https://ai.google.dev/gemini-api/docs/structured-output?hl=ko)
Readable Markdown	[Skip to main content](https://ai.google.dev/gemini-api/docs/structured-output#main-content) - [Gemini API](https://ai.google.dev/gemini-api/docs) - [Docs](https://ai.google.dev/gemini-api/docs) - [API reference](https://ai.google.dev/api) - [Get API key](https://aistudio.google.com/apikey) - [Cookbook](https://github.com/google-gemini/cookbook) - [Community](https://discuss.ai.google.dev/c/gemini-api/) - Get started - [Overview](https://ai.google.dev/gemini-api/docs) - [Quickstart](https://ai.google.dev/gemini-api/docs/quickstart) - [API keys](https://ai.google.dev/gemini-api/docs/api-key) - [Libraries](https://ai.google.dev/gemini-api/docs/libraries) - [Pricing](https://ai.google.dev/gemini-api/docs/pricing) - [Interactions API](https://ai.google.dev/gemini-api/docs/interactions) - [Coding agent setup](https://ai.google.dev/gemini-api/docs/coding-agents) - Models - [All models](https://ai.google.dev/gemini-api/docs/models) - [Gemini 3](https://ai.google.dev/gemini-api/docs/gemini-3) - [Nano Banana](https://ai.google.dev/gemini-api/docs/image-generation) - [Veo](https://ai.google.dev/gemini-api/docs/video) - [Lyria 3](https://ai.google.dev/gemini-api/docs/music-generation) - [Lyria Real Time](https://ai.google.dev/gemini-api/docs/realtime-music-generation) - [Imagen](https://ai.google.dev/gemini-api/docs/imagen) - [Text-to-speech](https://ai.google.dev/gemini-api/docs/speech-generation) - [Embeddings](https://ai.google.dev/gemini-api/docs/embeddings) - [Robotics](https://ai.google.dev/gemini-api/docs/robotics-overview) - Core capabilities - [Text](https://ai.google.dev/gemini-api/docs/text-generation) - [Documents](https://ai.google.dev/gemini-api/docs/document-processing) - [Structured outputs](https://ai.google.dev/gemini-api/docs/structured-output) - [Function calling](https://ai.google.dev/gemini-api/docs/function-calling) - [Long context](https://ai.google.dev/gemini-api/docs/long-context) - Agents - [Overview](https://ai.google.dev/gemini-api/docs/agents) - [Deep Research Agent](https://ai.google.dev/gemini-api/docs/deep-research) - Tools - [Overview](https://ai.google.dev/gemini-api/docs/tools) - [Google Search](https://ai.google.dev/gemini-api/docs/google-search) - [Google Maps](https://ai.google.dev/gemini-api/docs/maps-grounding) - [Code execution](https://ai.google.dev/gemini-api/docs/code-execution) - [URL context](https://ai.google.dev/gemini-api/docs/url-context) - [Computer Use](https://ai.google.dev/gemini-api/docs/computer-use) - [File Search](https://ai.google.dev/gemini-api/docs/file-search) - [Combine Tools and Function calling](https://ai.google.dev/gemini-api/docs/tool-combination) - Live API - [Overview](https://ai.google.dev/gemini-api/docs/live-api) - [Capabilities](https://ai.google.dev/gemini-api/docs/live-api/capabilities) - [Tool use](https://ai.google.dev/gemini-api/docs/live-api/tools) - [Session management](https://ai.google.dev/gemini-api/docs/live-api/session-management) - [Ephemeral tokens](https://ai.google.dev/gemini-api/docs/live-api/ephemeral-tokens) - [Best practices](https://ai.google.dev/gemini-api/docs/live-api/best-practices) - Optimization - [Overview](https://ai.google.dev/gemini-api/docs/optimization) - [Batch API](https://ai.google.dev/gemini-api/docs/batch-api) - [Flex inference](https://ai.google.dev/gemini-api/docs/flex-inference) - [Priority inference](https://ai.google.dev/gemini-api/docs/priority-inference) - [Context caching](https://ai.google.dev/gemini-api/docs/caching) - Guides - [Open AI compatibility](https://ai.google.dev/gemini-api/docs/openai) - [Media resolution](https://ai.google.dev/gemini-api/docs/media-resolution) - [Token counting](https://ai.google.dev/gemini-api/docs/tokens) - [Prompt engineering](https://ai.google.dev/gemini-api/docs/prompting-strategies) - Resources - [Release notes](https://ai.google.dev/gemini-api/docs/changelog) - [Deprecations](https://ai.google.dev/gemini-api/docs/deprecations) - [Rate limits](https://ai.google.dev/gemini-api/docs/rate-limits) - [Billing info](https://ai.google.dev/gemini-api/docs/billing) - [Migrate to Gen AI SDK](https://ai.google.dev/gemini-api/docs/migrate) - [API troubleshooting](https://ai.google.dev/gemini-api/docs/troubleshooting) - [Partner and library integrations](https://ai.google.dev/gemini-api/docs/partner-integration) - Policies - [Terms of service](https://ai.google.dev/gemini-api/terms) - [Available regions](https://ai.google.dev/gemini-api/docs/available-regions) - [Abuse monitoring](https://ai.google.dev/gemini-api/docs/usage-policies) - [Feedback information](https://ai.google.dev/gemini-api/docs/feedback-policies) - On this page - [Streaming](https://ai.google.dev/gemini-api/docs/structured-output#streaming) - [Structured outputs with tools](https://ai.google.dev/gemini-api/docs/structured-output#structured_outputs_with_tools) - [JSON schema support](https://ai.google.dev/gemini-api/docs/structured-output#json_schema_support) - [Type-specific properties](https://ai.google.dev/gemini-api/docs/structured-output#type-specific_properties) - [Model support](https://ai.google.dev/gemini-api/docs/structured-output#model_support) - [Structured outputs vs. function calling](https://ai.google.dev/gemini-api/docs/structured-output#structured_outputs_vs_function_calling) - [Best practices](https://ai.google.dev/gemini-api/docs/structured-output#best_practices) - [Limitations](https://ai.google.dev/gemini-api/docs/structured-output#limitations) You can configure Gemini models to generate responses that adhere to a provided JSON Schema. This ensures predictable, type-safe results and simplifies extracting structured data from unstructured text. Using structured outputs is ideal for: - Data extraction: Pull specific information like names and dates from text. - Structured classification: Classify text into predefined categories. - Agentic workflows: Generate structured inputs for tools or APIs. In addition to supporting JSON Schema in the REST API, the Google GenAI SDKs make it easy to define schemas using [Pydantic](https://docs.pydantic.dev/latest/) (Python) and [Zod](https://zod.dev/) (JavaScript). This example demonstrates how to extract structured data from text using basic JSON Schema types like `object`, `array`, `string`, and `integer`. ``` from google import genai from pydantic import BaseModel, Field from typing import List, Optional class Ingredient(BaseModel): name: str = Field(description="Name of the ingredient.") quantity: str = Field(description="Quantity of the ingredient, including units.") class Recipe(BaseModel): recipe_name: str = Field(description="The name of the recipe.") prep_time_minutes: Optional[int] = Field(description="Optional time in minutes to prepare the recipe.") ingredients: List[Ingredient] instructions: List[str] client = genai.Client() prompt = """ Please extract the recipe from the following text. The user wants to make delicious chocolate chip cookies. They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda, 1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar, 3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs. For the best part, they'll need 2 cups of semisweet chocolate chips. First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour, baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes. """ response = client.models.generate_content( model="gemini-3-flash-preview", contents=prompt, config={ "response_mime_type": "application/json", "response_json_schema": Recipe.model_json_schema(), }, ) recipe = Recipe.model_validate_json(response.text) print(recipe) ``` ``` import { GoogleGenAI } from "@google/genai"; import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema"; const ingredientSchema = z.object({ name: z.string().describe("Name of the ingredient."), quantity: z.string().describe("Quantity of the ingredient, including units."), }); const recipeSchema = z.object({ recipe_name: z.string().describe("The name of the recipe."), prep_time_minutes: z.number().optional().describe("Optional time in minutes to prepare the recipe."), ingredients: z.array(ingredientSchema), instructions: z.array(z.string()), }); const ai = new GoogleGenAI({}); const prompt = ` Please extract the recipe from the following text. The user wants to make delicious chocolate chip cookies. They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda, 1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar, 3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs. For the best part, they'll need 2 cups of semisweet chocolate chips. First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour, baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes. `; const response = await ai.models.generateContent({ model: "gemini-3-flash-preview", contents: prompt, config: { responseMimeType: "application/json", responseJsonSchema: zodToJsonSchema(recipeSchema), }, }); const recipe = recipeSchema.parse(JSON.parse(response.text)); console.log(recipe); ``` ``` package main import ( "context" "fmt" "log" "google.golang.org/genai" ) func main() { ctx := context.Background() client, err := genai.NewClient(ctx, nil) if err != nil { log.Fatal(err) } prompt := ` Please extract the recipe from the following text. The user wants to make delicious chocolate chip cookies. They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda, 1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar, 3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs. For the best part, they'll need 2 cups of semisweet chocolate chips. First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour, baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes. ` config := &genai.GenerateContentConfig{ ResponseMIMEType: "application/json", ResponseJsonSchema: map[string]any{ "type": "object", "properties": map[string]any{ "recipe_name": map[string]any{ "type": "string", "description": "The name of the recipe.", }, "prep_time_minutes": map[string]any{ "type": "integer", "description": "Optional time in minutes to prepare the recipe.", }, "ingredients": map[string]any{ "type": "array", "items": map[string]any{ "type": "object", "properties": map[string]any{ "name": map[string]any{ "type": "string", "description": "Name of the ingredient.", }, "quantity": map[string]any{ "type": "string", "description": "Quantity of the ingredient, including units.", }, }, "required": []string{"name", "quantity"}, }, }, "instructions": map[string]any{ "type": "array", "items": map[string]any{"type": "string"}, }, }, "required": []string{"recipe_name", "ingredients", "instructions"}, }, } result, err := client.Models.GenerateContent( ctx, "gemini-3-flash-preview", genai.Text(prompt), config, ) if err != nil { log.Fatal(err) } fmt.Println(result.Text()) } ``` ``` curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "contents": [{ "parts":[ { "text": "Please extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,\n3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they will need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes." } ] }], "generationConfig": { "responseMimeType": "application/json", "responseJsonSchema": { "type": "object", "properties": { "recipe_name": { "type": "string", "description": "The name of the recipe." }, "prep_time_minutes": { "type": "integer", "description": "Optional time in minutes to prepare the recipe." }, "ingredients": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the ingredient."}, "quantity": { "type": "string", "description": "Quantity of the ingredient, including units."} }, "required": ["name", "quantity"] } }, "instructions": { "type": "array", "items": { "type": "string" } } }, "required": ["recipe_name", "ingredients", "instructions"] } } }' ``` Example Response: ``` { "recipe_name": "Delicious Chocolate Chip Cookies", "ingredients": [ { "name": "all-purpose flour", "quantity": "2 and 1/4 cups" }, { "name": "baking soda", "quantity": "1 teaspoon" }, { "name": "salt", "quantity": "1 teaspoon" }, { "name": "unsalted butter (softened)", "quantity": "1 cup" }, { "name": "granulated sugar", "quantity": "3/4 cup" }, { "name": "packed brown sugar", "quantity": "3/4 cup" }, { "name": "vanilla extract", "quantity": "1 teaspoon" }, { "name": "large eggs", "quantity": "2" }, { "name": "semisweet chocolate chips", "quantity": "2 cups" } ], "instructions": [ "Preheat the oven to 375°F (190°C).", "In a small bowl, whisk together the flour, baking soda, and salt.", "In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy.", "Beat in the vanilla and eggs, one at a time.", "Gradually beat in the dry ingredients until just combined.", "Stir in the chocolate chips.", "Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes." ] } ``` ## Streaming You can stream structured outputs, which allows you to start processing the response as it's being generated, without having to wait for the entire output to be complete. This can improve the perceived performance of your application. The streamed chunks will be valid partial JSON strings, which can be concatenated to form the final, complete JSON object. ``` from google import genai from pydantic import BaseModel, Field from typing import Literal class Feedback(BaseModel): sentiment: Literal["positive", "neutral", "negative"] summary: str client = genai.Client() prompt = "The new UI is incredibly intuitive and visually appealing. Great job. Add a very long summary to test streaming!" response_stream = client.models.generate_content_stream( model="gemini-3-flash-preview", contents=prompt, config={ "response_mime_type": "application/json", "response_json_schema": Feedback.model_json_schema(), }, ) for chunk in response_stream: print(chunk.candidates[0].content.parts[0].text) ``` ``` import { GoogleGenAI } from "@google/genai"; import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema"; const ai = new GoogleGenAI({}); const prompt = "The new UI is incredibly intuitive and visually appealing. Great job! Add a very long summary to test streaming!"; const feedbackSchema = z.object({ sentiment: z.enum(["positive", "neutral", "negative"]), summary: z.string(), }); const stream = await ai.models.generateContentStream({ model: "gemini-3-flash-preview", contents: prompt, config: { responseMimeType: "application/json", responseJsonSchema: zodToJsonSchema(feedbackSchema), }, }); for await (const chunk of stream) { console.log(chunk.candidates[0].content.parts[0].text) } ``` ## Structured outputs with tools Gemini 3 lets you combine Structured Outputs with built-in tools, including [Grounding with Google Search](https://ai.google.dev/gemini-api/docs/google-search), [URL Context](https://ai.google.dev/gemini-api/docs/url-context), [Code Execution](https://ai.google.dev/gemini-api/docs/code-execution), [File Search](https://ai.google.dev/gemini-api/docs/file-search#structured-output), and [Function Calling](https://ai.google.dev/gemini-api/docs/function-calling). ``` from google import genai from pydantic import BaseModel, Field from typing import List class MatchResult(BaseModel): winner: str = Field(description="The name of the winner.") final_match_score: str = Field(description="The final match score.") scorers: List[str] = Field(description="The name of the scorer.") client = genai.Client() response = client.models.generate_content( model="gemini-3.1-pro-preview", contents="Search for all details for the latest Euro.", config={ "tools": [ {"google_search": {}}, {"url_context": {}} ], "response_mime_type": "application/json", "response_json_schema": MatchResult.model_json_schema(), }, ) result = MatchResult.model_validate_json(response.text) print(result) ``` ``` import { GoogleGenAI } from "@google/genai"; import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema"; const ai = new GoogleGenAI({}); const matchSchema = z.object({ winner: z.string().describe("The name of the winner."), final_match_score: z.string().describe("The final score."), scorers: z.array(z.string()).describe("The name of the scorer.") }); async function run() { const response = await ai.models.generateContent({ model: "gemini-3.1-pro-preview", contents: "Search for all details for the latest Euro.", config: { tools: [ { googleSearch: {} }, { urlContext: {} } ], responseMimeType: "application/json", responseJsonSchema: zodToJsonSchema(matchSchema), }, }); const match = matchSchema.parse(JSON.parse(response.text)); console.log(match); } run(); ``` ``` curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "contents": [{ "parts": [{"text": "Search for all details for the latest Euro."}] }], "tools": [ {"googleSearch": {}}, {"urlContext": {}} ], "generationConfig": { "responseMimeType": "application/json", "responseJsonSchema": { "type": "object", "properties": { "winner": {"type": "string", "description": "The name of the winner."}, "final_match_score": {"type": "string", "description": "The final score."}, "scorers": { "type": "array", "items": {"type": "string"}, "description": "The name of the scorer." } }, "required": ["winner", "final_match_score", "scorers"] } } }' ``` ## JSON schema support To generate a JSON object, set the `response_mime_type` in the generation configuration to `application/json` and provide a `response_json_schema`. The schema must be a valid [JSON Schema](https://json-schema.org/) that describes the desired output format. The model will then generate a response that is a syntactically valid JSON string matching the provided schema. When using structured outputs, the model will produce outputs in the same order as the keys in the schema. Gemini's structured output mode supports a subset of the [JSON Schema](https://json-schema.org/) specification. The following values of `type` are supported: - `string`: For text. - `number`: For floating-point numbers. - `integer`: For whole numbers. - `boolean`: For true/false values. - `object`: For structured data with key-value pairs. - `array`: For lists of items. - `null`: To allow a property to be null, include `"null"` in the type array (e.g., `{"type": ["string", "null"]}`). These descriptive properties help guide the model: - `title`: A short description of a property. - `description`: A longer and more detailed description of a property. ### Type-specific properties For `object` values: - `properties`: An object where each key is a property name and each value is a schema for that property. - `required`: An array of strings, listing which properties are mandatory. - `additionalProperties`: Controls whether properties not listed in `properties` are allowed. Can be a boolean or a schema. For `string` values: - `enum`: Lists a specific set of possible strings for classification tasks. - `format`: Specifies a syntax for the string, such as `date-time`, `date`, `time`. For `number` and `integer` values: - `enum`: Lists a specific set of possible numeric values. - `minimum`: The minimum inclusive value. - `maximum`: The maximum inclusive value. For `array` values: - `items`: Defines the schema for all items in the array. - `prefixItems`: Defines a list of schemas for the first N items, allowing for tuple-like structures. - `minItems`: The minimum number of items in the array. - `maxItems`: The maximum number of items in the array. ## Model support The following models support structured output: \| Model \| Structured Outputs \| \|---\|---\| \| Gemini 3.1 Pro Preview \| ✔️ \| \| Gemini 3 Flash Preview \| ✔️ \| \| Gemini 2.5 Pro \| ✔️ \| \| Gemini 2.5 Flash \| ✔️ \| \| Gemini 2.5 Flash-Lite \| ✔️ \| \| Gemini 2.0 Flash \| ✔️\* \| \| Gemini 2.0 Flash-Lite \| ✔️\* \| \ Note that Gemini 2.0 requires an explicit `propertyOrdering` list within the JSON input to define the preferred structure. You can find an example in this [cookbook](https://github.com/google-gemini/cookbook/blob/main/examples/Pdf_structured_outputs_on_invoices_and_forms.ipynb).* ## Structured outputs vs. function calling Both structured outputs and function calling use JSON schemas, but they serve different purposes: \| Feature \| Primary Use Case \| \|---\|---\| \| Structured Outputs \| Formatting the final response to the user. Use this when you want the model's answer to be in a specific format (e.g., extracting data from a document to save to a database). \| \| Function Calling \| Taking action during the conversation. Use this when the model needs to ask you to perform a task (e.g., "get current weather") before it can provide a final answer. \| ## Best practices - Clear descriptions: Use the `description` field in your schema to provide clear instructions to the model about what each property represents. This is crucial for guiding the model's output. - Strong typing: Use specific types (`integer`, `string`, `enum`) whenever possible. If a parameter has a limited set of valid values, use an `enum`. - Prompt engineering: Clearly state in your prompt what you want the model to do. For example, "Extract the following information from the text..." or "Classify this feedback according to the provided schema...". - Validation: While structured output guarantees syntactically correct JSON, it does not guarantee the values are semantically correct. Always validate the final output in your application code before using it. - Error handling: Implement robust error handling in your application to gracefully manage cases where the model's output, while schema-compliant, may not meet your business logic requirements. ## Limitations - Schema subset: Not all features of the JSON Schema specification are supported. The model ignores unsupported properties. - 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. Except as otherwise noted, the content of this page is licensed under the [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/), and code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0). For details, see the [Google Developers Site Policies](https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its affiliates. Last updated 2026-02-26 UTC.
Shard	189 (laksa)
Root Hash	1013294096244278789
Unparsed URL	dev,google!ai,/gemini-api/docs/structured-output s443