You can guarantee that a model's generated output always adheres to a specific schema so that you receive consistently formatted responses. For example, you might have an established data schema that you use for other tasks. If you have the model follow the same schema, you can directly extract data from the model's output without any post-processing.
To specify the structure of a model's output, define a response schema , which works like a blueprint for model responses. When you submit a prompt and include the response schema , the model's response always follows your defined schema.
You can control generated output when using the following models:
-
Gemini models:
-
Open models:
For Open Models, follow this user guide .
Example use cases
One use case for applying a response schema is to ensure that a model's response produces valid JSON and conforms to your schema. Generative model outputs can have some degree of variability, so including a response schema ensures that you always receive valid JSON. Consequently, your downstream tasks can reliably expect valid JSON input from generated responses.
Another example is to constrain how a model can respond. For example, you can
have a model annotate text with user-defined labels, not with labels that the
model produces. This constraint is useful when you expect a specific set of
labels such as positive
or negative
and don't want to receive a mixture of
other labels that the model might generate like good
, positive
, negative
,
or bad
.
Considerations
The following considerations discuss potential limitations if you plan on using a response schema:
- You must use the API to define and use a response schema. There's no console support.
- The size of your response schema counts towards the input token limit.
- Only certain output formats are supported, such as
application/jsonortext/x.enum. For more information, see theresponseMimeTypeparameter in the Gemini API reference . - Structured output supports a subset of the Vertex AI schema reference . For more information, see Supported schema fields .
-
A complex schema can result in an
InvalidArgument: 400error. Complexity might come from long property names, long array length limits, enums with many values, objects with lots of optional properties, or a combination of these factors.If you get this error with a valid schema, make one or more of the following changes to resolve the error:
- Shorten property names or enum names.
- Flatten nested arrays.
- Reduce the number of properties with constraints, such as numbers with minimum and maximum limits.
- Reduce the number of properties with complex constraints, such as
properties with complex formats like
date-time. - Reduce the number of optional properties.
- Reduce the number of valid values for enums.
Supported schema fields
Structured output supports the following fields from the Vertex AI schema . If you use an unsupported field, Vertex AI can still handle your request but ignores the field.
-
anyOf -
enum: onlystringenums are supported -
format -
items -
maximum -
maxItems -
minimum -
minItems -
nullable -
properties -
propertyOrdering* -
required
*
propertyOrdering
is specifically for structured output and
not part of the Vertex AI schema. This field defines the order in
which properties are generated. The listed properties must be unique and must be
valid keys in the properties
dictionary.
For the format
field, Vertex AI supports the following values: date
, date-time
, duration
, and time
. The description and format of each value is
described in the OpenAPI Initiative Registry
Before you begin
Define a response schema to specify the structure of a model's output, the field names, and the expected data type for each field. Use only the supported fields as listed in the Considerations section. All other fields are ignored.
Include your response schema as part of the responseSchema
field only. Don't
duplicate the schema in your input prompt. If you do, the generated output might
be lower in quality.
For sample schemas, see the Example schemas and model responses section.
Model behavior and response schema
When a model generates a response, it uses the field name and context from your prompt. As such, we recommend that you use a clear structure and unambiguous field names so that your intent is clear.
By default, fields are optional, meaning the model can populate the fields or skip them. You can set fields as required to force the model to provide a value. If there's insufficient context in the associated input prompt, the model generates responses mainly based on the data it was trained on.
If you aren't seeing the results you expect, add more context to your input prompts or revise your response schema. For example, review the model's response without structured output to see how the model responds. You can then update your response schema that better fits the model's output.
Send a prompt with a response schema
By default, all fields are optional, meaning a model might generate a response to a field. To force the model to always generate a response to a field, set the field as required.
Python
Install
pip install --upgrade google-genai
To learn more, see the SDK reference documentation .
Set environment variables to use the Gen AI SDK with Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT = GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION = global export GOOGLE_GENAI_USE_VERTEXAI = True
Go
Learn how to install or update the Go .
To learn more, see the SDK reference documentation .
Set environment variables to use the Gen AI SDK with Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT = GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION = global export GOOGLE_GENAI_USE_VERTEXAI = True
REST
Before using any of the request data, make the following replacements:
- GENERATE_RESPONSE_METHOD
: The type of response that you want the model to generate.
Choose a method that generates how you want the model's response to be returned:
-
streamGenerateContent: The response is streamed as it's being generated to reduce the perception of latency to a human audience. -
generateContent: The response is returned after it's fully generated.
-
- LOCATION : The region to process the request.
- PROJECT_ID : Your project ID .
- MODEL_ID : The model ID of the multimodal model that you want to use.
- ROLE
:
The role in a conversation associated with the content. Specifying a role is required even in
singleturn use cases.
Acceptable values include the following:
-
USER: Specifies content that's sent by you.
-
- TEXT : The text instructions to include in the prompt.
- RESPONSE_MIME_TYPE
: The format type of the
generated candidate text. For a list of supported values, see the
responseMimeTypeparameter in the Gemini API . - RESPONSE_SCHEMA : Schema for the model to follow when generating responses. For more information, see the Schema reference.
HTTP method and URL:
POST https:// LOCATION -aiplatform.googleapis.com/v1/projects/ PROJECT_ID /locations/ LOCATION /publishers/google/models/ MODEL_ID : GENERATE_RESPONSE_METHOD
Request JSON body:
{ "contents": { "role": " ROLE ", "parts": { "text": " TEXT " } }, "generation_config": { "responseMimeType": " RESPONSE_MIME_TYPE ", "responseSchema": RESPONSE_SCHEMA , } }
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https:// LOCATION -aiplatform.googleapis.com/v1/projects/ PROJECT_ID /locations/ LOCATION /publishers/google/models/ MODEL_ID : GENERATE_RESPONSE_METHOD "
PowerShell
Save the request body in a file named request.json
,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https:// LOCATION -aiplatform.googleapis.com/v1/projects/ PROJECT_ID /locations/ LOCATION /publishers/google/models/ MODEL_ID : GENERATE_RESPONSE_METHOD " | Select-Object -Expand Content
You should receive a JSON response similar to the following.
Example curl command
LOCATION
=
"us-central1"
MODEL_ID
=
"gemini-2.5-flash"
PROJECT_ID
=
"test-project"
GENERATE_RESPONSE_METHOD
=
"generateContent"
cat <<
EOF >
request.json {
"contents"
:
{
"role"
:
"user"
,
"parts"
:
{
"text"
:
"List a few popular cookie recipes."
}
}
,
"generation_config"
:
{
"maxOutputTokens"
:
2048
,
"responseMimeType"
:
"application/json"
,
"responseSchema"
:
{
"type"
:
"array"
,
"items"
:
{
"type"
:
"object"
,
"properties"
:
{
"recipe_name"
:
{
"type"
:
"string"
,
}
,
}
,
"required"
:
[
"recipe_name"
]
,
}
,
}
}
}
EOF
curl
\
-X
POST
\
-H
"Authorization: Bearer
$(
gcloud
auth
print-access-token )
"
\
-H
"Content-Type: application/json"
\
https:// ${
LOCATION
}
-aiplatform.googleapis.com/v1/projects/ ${
PROJECT_ID
}
/locations/ ${
LOCATION
}
/publishers/google/models/ ${
MODEL_ID
}
: ${
GENERATE_RESPONSE_METHOD
}
\
-d
'@request.json'
Example schemas for JSON output
The following sections demonstrate a variety of sample prompts and response schemas. A sample model response is also included after each code sample.
- Forecast the weather for each day of the week in an array
- Classify a product with a well-defined enum
Forecast the weather for each day of the week
The following example outputs a forecast
object for each day
of the week that includes an array of properties such as the expected
temperature and humidity level for the day. Some properties are set to nullable
so the model can return a null value when it doesn't have enough context to
generate a meaningful response. This strategy helps reduce hallucinations.
Python
Install
pip install --upgrade google-genai
To learn more, see the SDK reference documentation .
Set environment variables to use the Gen AI SDK with Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT = GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION = global export GOOGLE_GENAI_USE_VERTEXAI = True
Go
Learn how to install or update the Go .
To learn more, see the SDK reference documentation .
Set environment variables to use the Gen AI SDK with Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT = GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION = global export GOOGLE_GENAI_USE_VERTEXAI = True
Classify a product
The following example includes enums where the model must classify an object's type and condition from a list of given values.
Python
Install
pip install --upgrade google-genai
To learn more, see the SDK reference documentation .
Set environment variables to use the Gen AI SDK with Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT = GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION = global export GOOGLE_GENAI_USE_VERTEXAI = True
Go
Learn how to install or update the Go .
To learn more, see the SDK reference documentation .
Set environment variables to use the Gen AI SDK with Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT = GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION = global export GOOGLE_GENAI_USE_VERTEXAI = True
Node.js
Install
npm install @google/genai
To learn more, see the SDK reference documentation .
Set environment variables to use the Gen AI SDK with Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT = GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION = global export GOOGLE_GENAI_USE_VERTEXAI = True
Java
Learn how to install or update the Java .
To learn more, see the SDK reference documentation .
Set environment variables to use the Gen AI SDK with Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT = GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION = global export GOOGLE_GENAI_USE_VERTEXAI = True
