Structured Output as a Contract

Schema, validate, retry

When another program consumes the model's output, define a schema (fields, types, allowed values), ask for it explicitly with an example, and use the provider's structured output / JSON mode features where available. Still validate every response in code: check it parses, required fields exist and types are right. On failure, retry once with the error message, then fall back or escalate. Keep schemas small and flat; every optional field is another chance for inconsistency.

Validating model output against required fields, run

I ran this with plain Python 3 (standard library only); the data is made-up example data. Four sample outputs: one valid, one missing priority, one with priority as text instead of a number, and one chatty reply that is not JSON at all.

import json
required = {"intent": str, "priority": int}
def check(raw):
    try:
        data = json.loads(raw)
    except json.JSONDecodeError as e:
        return f"not JSON ({e.msg})"
    for key, typ in required.items():
        if key not in data:
            return f"missing {key}"
        if not isinstance(data[key], typ):
            return f"{key} should be {typ.__name__}"
    return "valid"
for raw in ['{"intent": "refund", "priority": 2}', '{"intent": "refund"}', '{"intent": "refund", "priority": "high"}', "Sure! Here is the JSON:"]:
    print(f"{check(raw):<22} <- {raw}")

Output:

valid                  <- {"intent": "refund", "priority": 2}
missing priority       <- {"intent": "refund"}
priority should be int <- {"intent": "refund", "priority": "high"}
not JSON (Expecting value) <- Sure! Here is the JSON:

Retry with the error

When validation fails, send the specific error back once (for example: priority must be an integer) instead of repeating the same prompt.

Quick check: Why validate structured output even when using JSON mode?

• Responses can still miss fields, use wrong types or be truncated
• JSON mode guarantees business correctness
• Validation trains the model
• It is only needed for images