Output schema max_string_length: descriptions use a 120,000 budget

If a large output_schema fails with 400 output_schema_invalid and the rule max_string_length, the schema went over a document-wide budget of 120,000 characters. The budget is summed over every property name, key and string value in the whole document, so no single field has to be long (Structured output). Shorten the description annotations first, then use $defs so a repeated shape is written once.

The four size limits

A schema can pass the other three and still fail the last one. A long description on each of 400 properties is the usual cause.

How to get under the budget

Sume reports every violation in one 400, so a schema over two limits shows both in details.violations[]. Switch on rule, not on the message text.

• Cut description text to what the agent needs to fill the field. Keep it to one short sentence.
• Move a repeated object shape into root $defs and point to it with $ref. The shape is counted once.
• Drop examples and title annotations. They are allowed, and they use the budget.
• Split a very large Format output into two runs with a smaller schema each, and continue with previous_run_id.

Count it before you send it

The check is cheap to mirror. This script counts the characters of every key and string value in a schema file, so you see the total before the API does.

import json, sys

def total(node):
    if isinstance(node, dict):
        return sum(len(k) + total(v) for k, v in node.items())
    if isinstance(node, list):
        return sum(total(v) for v in node)
    if isinstance(node, str):
        return len(node)
    return 0

schema = json.load(open(sys.argv[1]))
print(total(schema), "of 120000")