Function calling schema validation bug: array parameters with prefixItems rejected (missing items error)

API Bugs
1

Problem

When defining a function tool with an array parameter that uses prefixItems (valid JSON Schema 2020-12 syntax), the OpenAI API rejects the request with a 400 Bad Request error.

Example request (shortened for clarity):

{
  "model": "gpt-4o",
  "messages": [
    { "role": "user", "content": "Hello, what’s the weather in Shanghai today?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "parameters": {
          "type": "object",
          "properties": {
            "date": {
              "type": "string",
              "description": "Date, format YYYY-MM-DD"
            },
            "coords": {
              "type": "array",
              "minItems": 2,
              "maxItems": 2,
              "prefixItems": [
                { "type": "number" },
                { "type": "number" }
              ],
              "description": "Coordinates (lat, lon). Example: [31.14, 121.29]"
            }
          },
          "required": ["date", "coords"]
        }
      }
    }
  ]
}

Error Response

400 Bad Request
{
  "error": {
    "message": "Invalid schema for function 'get_weather': In context=('properties', 'coords'), array schema missing items.",
    "type": "invalid_request_error",
    "param": "tools[0].function.parameters",
    "code": "invalid_function_parameters"
  }
}

Expected Behavior

According to the official API documentation:

  • parameters should accept a valid JSON Schema object.

  • JSON Schema 2020-12 allows prefixItems for tuple validation (fixed-length arrays).

  • The schema above is valid JSON Schema.

Therefore, the API should accept this request instead of rejecting it.

Actual Behavior

  • The API rejects schemas using prefixItems (tuple form).

  • The error suggests the API only accepts the older items keyword for arrays.

  • This means the implementation does not fully align with the documented claim of “accepting JSON Schema.”

Notes

  • Omitting prefixItems and using items: { "type": "number" } works, but it loses tuple validation (e.g., enforcing exactly two numbers).

  • The issue appears across all current models (gpt-4o, gpt-4.1, etc.).

Request

Please confirm:

  • Is this a bug (API not supporting modern JSON Schema features like prefixItems)?

  • Or is the documentation incorrect (only older JSON Schema draft supported)?

Either the docs or the implementation should be updated for consistency.

2

Additional Findings

After further testing, it seems the API does not even support the older JSON Schema draft-07 / 2019-09 tuple form using an items: [ ... ] array.

Example schema (with both prefixItems and items provided for compatibility):

"coords": {
  "type": "array",
  "minItems": 2,
  "maxItems": 2,
  "prefixItems": [
    { "type": "number" },
    { "type": "number" }
  ],
  "items": [
    { "type": "number" },
    { "type": "number" }
  ],
  "description": "Coordinates (lat, lon)"
}

Error Response

400 Bad Request
{
  "error": {
    "message": "Invalid schema for function 'get_weather': [{'type': 'number'}, {'type': 'number'}] is not of type 'object', 'boolean'.",
    "type": "invalid_request_error",
    "param": "tools[0].function.parameters",
    "code": "invalid_function_parameters"
  }
}

Implications

  • This means tuple validation cannot be expressed at all (neither via prefixItems nor via legacy items: []).

  • The only array form currently accepted is the simplified schema:

"coords": {
  "type": "array",
  "items": { "type": "number" }
}

…but this loses the ability to enforce fixed-length arrays or positional typing.

Inconsistency

  • The API docs state that parameters should follow JSON Schema.

  • In practice, the implementation seems to only accept a narrow subset of JSON Schema (object properties + simple array items object).

  • Harmony’s internal format converts these schemas into TypeScript definitions — but without tuple support, this translation is inconsistent and misleading.

Request

Could the team clarify:

  1. Which subset of JSON Schema is officially supported?

  2. Whether tuple validation (items: [] or prefixItems) is on the roadmap?

At the moment, the API and documentation are out of sync, and developers cannot accurately express tuple-like parameters.