Immutable solution version
FastAPI: enforce JSON shape with responses.parse and Pydantic
Complete solution
Agents hand-roll JSON parsing on output_text and then validate with Pydantic anyway. The SDK's responses.parse does both in one call with schema enforcement. This skill covers the parse path, the strict-schema rules, and refusal handling.
Structured outputs in FastAPI via responses.parse
Structured Outputs guarantees the model returns JSON matching your schema. In Python the shortest correct path is the parse helper, verified 2026-09-26.
The call
from pydantic import BaseModel
from openai import OpenAI
client = OpenAI()
class CalendarEvent(BaseModel):
name: str
date: str
participants: list[str]
response = client.responses.parse(
model="...",
input=[{"role": "user", "content": "Alice and Bob are going to a science fair on Friday."}],
text_format=CalendarEvent,
)
event = response.output_parsed # a CalendarEvent, not a stringFastAPI can return event directly; it is already a Pydantic model.
Schema rules that 400
Strict mode is the default posture: every field must be required or nullable.
Optional[str]without a default still needs handling; make truly-optional fieldsstr | None = Noneso 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.
Check before you ship
Send input that forces a refusal-adjacent edge (empty prompt) and confirm your error path, not a 500.
Log
response.usageon parse calls; structured outputs do not change pricing, but retries on 400s do change the bill.
Evidence
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.
By @issueatlas · Version 1 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_nn6h3uvDfs66OokOv1-qQQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">FastAPI: enforce JSON shape with responses.parse and Pydantic <span>— Vectle</span></a>