All postsAI

What structured outputs don't check in your LLM data

What OpenAI and Anthropic strict schemas actually guarantee, and the validation layer, dead-letter table and drift checks you still need behind them.

Johnny Unar9 min read

01

what the provider actually guarantees

If you extract invoices, tickets or contracts with an LLM and write the result to a database, you've probably turned on structured outputs and stopped seeing parse errors. That part works. The trouble is that a response which matches your schema can still carry a wrong total, an invented SKU or a confident enum value that nobody would have picked, and none of that shows up as an error anywhere.

It helps to be exact about what each mode promises. The older JSON mode (response_format: {"type": "json_object"} in OpenAI's Chat Completions, text.format in the Responses API) only promises syntactically valid JSON. OpenAI's own docs say it does not guarantee the output matches any particular schema. Strict structured outputs are a different thing: OpenAI shipped them on 6 August 2024, both as response_format with type: "json_schema" and strict: true and as strict: true on function definitions. The model's decoding is constrained to the schema, so required keys are present, types match and enum fields contain one of your values.

Anthropic took longer. Until November 2025 the usual trick was to define a tool with an input schema and force the model to call it, which shapes the output well but doesn't constrain decoding. Structured outputs arrived as a public beta on 14 November 2025 (header structured-outputs-2025-11-13, Sonnet 4.5 and Opus 4.1 at first) and came out of beta on 29 January 2026, when the parameter moved from output_format to output_config.format. Strict tool use ("strict": true on a tool definition) is the same mechanism applied to tool inputs.

The two providers don't accept the same JSON Schema subset, and this matters when you generate the schema from your models. OpenAI's strict mode requires every property to be listed in required (optional fields become a union with null), requires additionalProperties: false on every object, and supports pattern, a fixed list of format values, minimum, maximum, multipleOf, and minItems/maxItems. It rejects allOf, not and the if/then/else family. Anthropic's current docs list minimum, maximum, multipleOf, minLength and maxLength as unsupported, and minItems only for the values 0 and 1. A raw request that uses them gets a 400, while the Python and TypeScript SDK helpers strip those keywords, append them to the field description and, for the helpers that validate, check the response against the original schema on your side. So on Anthropic a "minimum": 0 is a hint to the model plus a client-side check, not a decoding guarantee.

Neither provider can express a rule that spans two fields. "Line items add up to the subtotal" and "the due date comes after the invoice date" are outside JSON Schema entirely, and they're exactly the rules that keep financial data coherent.

02

the failures a valid schema lets through

The classic case is an enum that's always valid and sometimes wrong. Give a field payment_terms the values net_14, net_30, net_60 and immediate, and constrained decoding guarantees one of the four. On a blurry scan with no visible terms, the model still has to pick one, because the grammar gives it no other option. You get a plausible value, a passing schema and a wrong record in the accounting system.

The fix is cheap: add an explicit unknown (or not_stated) value to every enum where "none of these" is a real answer, and route those records to review instead of treating them as data. The same goes for nullable fields. If the document might not contain a due date, make the field date | null and tell the model in the field description that null is the right answer when the date isn't printed. A model forced to fill a required string will fill it.

Free-text fields have no such guard. An extracted SKU that matches your pattern regex is indistinguishable from a real one at the schema layer, even when the model made it up because the original was smudged. The only defence is checking it against something you know, such as your product table or the vendor's catalogue.

Arithmetic is the last big category. Constrained decoding works token by token, so it can force total to be a number but has no way to make it equal the sum of line items the model wrote a few hundred tokens earlier. For anything financial we'd treat a reconciliation check as mandatory.

03

check the stop reason before you parse

A constrained response can still be cut off. If generation hits the output token limit, you get JSON that stops mid-string and doesn't parse, not a shorter object that happens to validate. OpenAI's Responses API marks this with status: "incomplete" and incomplete_details.reason: "max_output_tokens" (Chat Completions uses finish_reason: "length"), and Anthropic returns stop_reason: "max_tokens" with a note in the docs that the output may not match the schema.

Refusals are the other exception. Both providers let the model refuse even with a schema, and a refusal doesn't follow your schema. OpenAI returns a separate refusal field, and Anthropic returns stop_reason: "refusal" with a 200 status. Anthropic's docs also mention that asking for step-by-step reasoning inside a schema property can trigger a refusal, so ask for a short explanation instead.

So the first thing your handler does is look at why generation stopped, and only then parse. A truncated response is not worth retrying with the same token budget and the same document, because it will usually truncate again. Raise the limit, split the document, or send it to the dead-letter table with the raw text.

04

a contract layer in pydantic

Validation belongs in your code, close to the database write, as a model written to reject things rather than describe them. This contract is the whole invoice, with money as Decimal, blank strings rejected after stripping, unknown keys forbidden and the cross-field rules in one validator:

python
1from datetime import date
2from decimal import Decimal
3from typing import Annotated, Literal
4
5from pydantic import BaseModel, ConfigDict, Field, StringConstraints, model_validator
6
7Money = Annotated[Decimal, Field(max_digits=12, decimal_places=2)]
8NonBlank = Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)]
9
10
11class LineItem(BaseModel):
12 model_config = ConfigDict(extra="forbid")
13
14 description: NonBlank
15 quantity: Annotated[Decimal, Field(gt=0)]
16 unit_price: Money
17 amount: Money
18
19
20class Invoice(BaseModel):
21 model_config = ConfigDict(extra="forbid")
22
23 vendor_name: NonBlank
24 invoice_date: date
25 due_date: date | None
26 currency: Literal["CZK", "EUR", "USD"]
27 payment_terms: Literal["net_14", "net_30", "net_60", "immediate", "unknown"]
28 line_items: Annotated[list[LineItem], Field(min_length=1)]
29 subtotal: Money
30 vat: Money
31 total: Money
32
33 @model_validator(mode="after")
34 def check_invariants(self) -> "Invoice":
35 if not date(2000, 1, 1) <= self.invoice_date <= date.today():
36 raise ValueError(f"invoice_date {self.invoice_date} is outside the plausible range")
37 if self.due_date is not None and self.due_date < self.invoice_date:
38 raise ValueError("due_date is before invoice_date")
39 for i, item in enumerate(self.line_items):
40 if (item.quantity * item.unit_price).quantize(Decimal("0.01")) != item.amount:
41 raise ValueError(f"line_items[{i}]: quantity * unit_price != amount")
42 if sum(item.amount for item in self.line_items) != self.subtotal:
43 raise ValueError("line item amounts do not add up to subtotal")
44 if self.subtotal + self.vat != self.total:
45 raise ValueError("subtotal + vat != total")
46 return self

A few details are deliberate. model_validate_json parses JSON numbers straight into Decimal, so 1234.5 arrives exact and the equality checks need no float tolerance. decimal_places=2 turns a VAT of 777.745 into a validation error instead of silently rounding it. A plain Field(min_length=1) accepts " ", which is why NonBlank strips first. And due_date: date | None has no default on purpose, so the field is required but nullable, which is the shape OpenAI's strict mode wants anyway. The code runs on current Pydantic 2 (2.14 at the time of writing), and the date | None syntax needs Python 3.10 or newer.

Don't send this model's generated schema to the provider unchanged. Invoice.model_json_schema() renders every Decimal as anyOf number or string and drops max_digits and decimal_places, and it emits minLength, which Anthropic rejects in a raw request. Treat the provider schema as a looser projection of the contract that steers the model, and the Pydantic model as the thing that decides what gets stored. The contract is also the most honest documentation of what your pipeline assumes, so version it (invoice.v3) and keep the old version around while a prompt change rolls out.

05

retries and a dead-letter table

When validation fails, one retry with the errors fed back is worth it, because the model often fixes a specific, named mistake. Format the errors from ValidationError.errors() rather than dumping str(e), and keep the budget small:

python
1from dataclasses import dataclass
2
3from pydantic import ValidationError
4
5from contract import Invoice
6
7
8@dataclass
9class ModelReply:
10 text: str
11 stop_reason: str # normalised: "stop", "length", "refusal"
12
13
14class Truncated(Exception):
15 pass
16
17
18class Refused(Exception):
19 pass
20
21
22def format_errors(e: ValidationError) -> str:
23 lines = []
24 for err in e.errors(include_url=False):
25 where = ".".join(str(p) for p in err["loc"]) or "(root)"
26 lines.append(f"- {where}: {err['msg']}")
27 return "\n".join(lines)
28
29
30def extract(document: str, call_model, max_attempts: int = 2) -> Invoice:
31 messages = [{"role": "user", "content": document}]
32 for attempt in range(max_attempts):
33 reply = call_model(messages)
34 if reply.stop_reason == "length":
35 raise Truncated("output hit the token limit")
36 if reply.stop_reason == "refusal":
37 raise Refused(reply.text)
38 try:
39 return Invoice.model_validate_json(reply.text)
40 except ValidationError as e:
41 if attempt == max_attempts - 1:
42 raise
43 messages += [
44 {"role": "assistant", "content": reply.text},
45 {"role": "user", "content": "The extraction failed these checks:\n"
46 + format_errors(e)
47 + "\nRe-read the document and return the full object again."},
48 ]

call_model is your provider wrapper, which maps OpenAI's and Anthropic's stop signals onto the three normalised values. A total that doesn't reconcile comes back to the model as - (root): Value error, subtotal + vat != total, which is specific enough to act on.

Whatever still fails goes to a dead-letter table, not to an exception that kills a batch of five hundred documents and not to a log line nobody reads. The pipeline carries on, nothing is silently dropped and nothing is silently accepted:

sql
1CREATE TABLE extraction_dead_letters (
2 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
3 document_id uuid NOT NULL,
4 contract text NOT NULL, -- e.g. 'invoice.v3'
5 model text NOT NULL,
6 prompt_version text NOT NULL,
7 stop_reason text,
8 raw_output text, -- text, not jsonb: truncated output is not valid JSON
9 errors jsonb, -- ValidationError.errors(), or null for truncation/refusal
10 created_at timestamptz NOT NULL DEFAULT now(),
11 resolved_at timestamptz,
12 resolved_by text
13);
14
15CREATE INDEX extraction_dead_letters_open
16 ON extraction_dead_letters (contract, created_at)
17 WHERE resolved_at IS NULL;

The columns are the ones you need when you go looking for patterns later: which contract, model and prompt version produced the failure, why generation stopped, and the exact errors. Records with payment_terms = 'unknown' can go to the same review queue even though they validated, because they're the model telling you it didn't know.

06

watching the distribution, not just the failures

Validation catches records that break a rule. It can't catch a model that has started picking net_30 for documents that used to come out as net_14, because each record is still valid on its own. That kind of drift only shows up in aggregate, usually right after a model upgrade or a prompt edit, so store the model and prompt version on every extracted row and look at the value distribution per version:

sql
1SELECT date_trunc('week', created_at) AS week,
2 model,
3 prompt_version,
4 payment_terms,
5 count(*) AS n,
6 round(100.0 * count(*) / sum(count(*)) OVER (PARTITION BY date_trunc('week', created_at), model, prompt_version), 1) AS pct
7FROM invoice_extractions
8WHERE created_at > now() - interval '8 weeks'
9GROUP BY 1, 2, 3, 4
10ORDER BY 1, 2, 3, n DESC;

If net_30 jumps from 20 to 60 percent in the week p7 replaced p6 and your customers didn't change, the prompt changed the answers. The same query on the unknown share tells you whether a change made the model more or less willing to admit it can't read a field, and a falling unknown rate isn't automatically good news. Run it per field that drives money or routing, alert on large week-over-week shifts, and pair it with a small random sample of records that a person checks against the source document. Random sampling is what finds the systematic mistake that every individual check passes, the one where a reviewer looks at a handful of records and notices they're all wrong in the same way.

Thanks for reading.
Johnny Unar

Written by

Johnny Unar

Keep reading

Stop patching.Start building.

Tell us what's slowing you down. We'll bring coffee and opinions.