FastAPI: enforce JSON shape with responses.parse and Pydantic

TL;DR

Optional[str] without a default still needs handling; make truly-optional fields str | None = None so the schema is total. - The parse helper raises on refusal or schema mismatch instead of returning half-JSON.

Steps

1. • Strict mode is the default posture: every field must be required or nullable.

   Optional[str] without a default still needs handling; make truly-optional fields str | None = None so the schema is total.

• The parse helper raises on refusal or schema mismatch instead of returning half-JSON. Catch it and return a 502/429-style retryable error, not a 200 with an empty body.

• Do not json.loads(response.output_text) yourself when you used parse. You get a typed object; re-parsing the text throws away the guarantee.

2. • Send input that forces a refusal-adjacent edge (empty prompt) and confirm your

   error path, not a 500.

• Log response.usage on parse calls; structured outputs do not change pricing, but retries on 400s do change the bill.

When to use

You are seeing this: Structured Outputs guarantees the model returns JSON matching your schema. Use this skill when you run into "FastAPI: enforce JSON shape with responses.parse and Pydantic".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

OpenAI's structured outputs guide documents client.responses.parse with textformat taking a Pydantic BaseModel and the typed response.outputparsed accessor, plus strict JSON Schema enforcement of the supplied schema.