Schema used in FunctionCalling and ResponseSchema diverges

Gemini API
1

Hi,

It’s a bit confusing that the " Represents a select subset of an OpenAPI 3.0 schema object." for the definition of function_declarations in Function Calling is different to the definition of response_schema in Structured Output.

Using the nullable property renders an HTTP 400 Bad Request response from the Gemini API.

In Structured Output the information provided in the two sections

  • “Here’s a pseudo-JSON representation of all the Schema fields” and
  • “Here are some example schemas showing valid type-and-field combinations:”

diverges. Former has a boolean property whereas latter has an array. Meaning that the following serialization.

{
  "model" : "models/gemini-2.0-flash-exp",
  "contents" : [ {
    "role" : "user",
    "parts" : [ {
      "text" : "We are trying test a method that describes the format of attributes."
    } ]
  } ],
  "tools" : [ {
    "functionDeclarations" : [ {
      "name" : "test_nullable",
      "parameters" : {
        "type" : "object",
        "properties" : {
          "number_nullable" : {
            "type" : "number",
            "description" : "floating point number",
            "format" : "double"
          },
          "string_nullable" : {
            "type" : "string"
          }
        },
        "required" : [ "number_nullable", "string_nullable" ],
        "nullable" : [ "number_nullable" ]
      }
    } ]
  } ]
}

is supposedly valid. At least according to the Google documentation.

However, referring to the OpenAPI 3.0 Schema of nullable there is no such array described.

This seems to align with the Schema reference used in Function Calling.

There are also differences between the allowed value of the type parameter as described in the above linked documentation.

Diccovery API

Schema uses the two following properties and values.

        "format": {
          "description": "Optional. The format of the data. This is used only for primitive datatypes. Supported formats: for NUMBER type: float, double for INTEGER type: int32, int64 for STRING type: enum, date-time",
          "type": "string"
        },

       "type": {
          "description": "Required. Data type.",
          "enum": [
            "TYPE_UNSPECIFIED",
            "STRING",
            "NUMBER",
            "INTEGER",
            "BOOLEAN",
            "ARRAY",
            "OBJECT"
          ]
      }

Function Calling

Here, the statement is type (string): The data type of the parameter, such as string, integer, boolean. Followed by If the parameter value is always an integer, set the type to integer rather than number a bit further below.

Structured Output

Well, the documentation says

The following list maps each Type to valid fields for that type:

  • string → enum, format
  • integer → format
  • number → format
  • bool
  • array → minItems, maxItems, items
  • object → properties, required, propertyOrdering, nullable

But the example assigns a value of datetime instead of the allowed date-time.

Conclusion

It would be appreciated that both - Function Calling and Structured Output - use the same select subset of an OpenAPI 3.0 schema object consistently.

Thanks.

@GUNAND_MAYANGLAMBAM @dynamicwebpaige @Vishal

3

This is great feedback - thanks for flagging JoKi! I’ve relayed this to the engineering team.

1 Like