JSON Schema Design for Extracted Document Data

A JSON schema for extracted document data is the main engineering lever that determines extraction accuracy, validation behavior, and downstream reliability. It is not a formatting detail bolted on after the real work of choosing a model or tuning a pipeline. Most teams treat schema design as the last step: pick the extraction model first, then define the output shape to match whatever it happens to return. That order is backwards.

The schema is what the model is told to find. It is what validation checks against, what human reviewers get routed to inspect, and what compliance controls apply to once data leaves the pipeline. All of that happens downstream of the schema. A vague or under-specified schema doesn't just produce messy JSON. It actively lowers extraction accuracy by giving the model too little to work with. And once a value is lost or misrepresented at extraction time, no downstream LLM, RAG pipeline, or business system can recover it. The error propagates forward, and the only fix is re-extraction. Schema design deserves the same rigor as model selection, and every section that follows works through what that rigor looks like, field by field.

Field descriptions and extraction accuracy before validation

A string field with no description is an open question, and the model will answer it with whatever seems plausible. That's the condition that produces hallucination instead of extraction: the model isn't wrong because it's careless, it's wrong because nothing in the schema told it what counts as right.

Take a field labeled "the invoice date." On a typical invoice, that phrase could mean the issue date, the due date, or the service period end date, three distinct fields that often appear on the same page within a few lines of each other. A description that stops at "the invoice date" leaves the model to guess among them. A description that says "the date the invoice was issued by the seller, typically found near the invoice number in the document header, formatted as it appears on the source" gives the model a location, a boundary against neighboring fields, and a formatting expectation. Same field, same model, very different odds of getting it right.

Amazon's PARSE research names the root of this problem directly: JSON schemas were built as contracts between human developers and static systems, not as instructions for an LLM agent reading a document in real time. Ambiguous or incomplete specifications, including unclear entity boundaries and conflicting requirements, lead to frequent hallucinations and unreliable agent behavior. The fix is to write every description as though explaining the field to a capable reader who has never seen this document type: what the value is, where it tends to appear, what format to expect, and what to do if it's missing. This discipline matters even more for extraction APIs that support custom schemas, since the quality and clarity of the schema descriptions directly determine the accuracy of the values the pipeline hands back.

Past a certain number of fields, a model's ability to attend to every description degrades, and accuracy drops across the board rather than on any one field, a failure mode worth planning for as schemas grow. The practical response is to split a sprawling schema into smaller, focused sub-schemas by document section, rather than letting one schema grow into a single unmanageable block.

Type constraints, format rules, and the naming decisions that prevent silent errors

Every type, format, and naming decision in a schema either catches a wrong value or lets one slip through. There's no neutral choice here: a loose type is a standing invitation for a silent error to pass validation and reach a downstream system looking correct.

Start with type specificity. Amounts, counts, and totals belong in JSON as numbers, not strings. Booleans belong as true or false literals, not as "1"/"0" strings or integer flags. Type coercion across languages is fragile, and a field that's sometimes a string and sometimes a number will eventually break a consumer that assumed one or the other.

Currency fields deserve a specific pattern: store the amount in the smallest currency unit, as an integer. A value of "amount": 1999 unambiguously means the corresponding dollar figure in cents, with no floating-point rounding to worry about. Compare that to storing "19.99" as a float, where repeated arithmetic across thousands of invoices can drift by fractions of a cent and throw off a reconciliation report that depends on exact totals.

Dates follow a parallel logic. They're among the most common sources of extraction bugs, mostly because source documents are inconsistent: DD/MM/YYYY on one invoice, MM-DD-YYYY on the next, sometimes within the same vendor's own document set. The schema should require ISO 8601 with an explicit timezone designator, UTC or "Z" as the default, with numeric offsets like +05:30 also acceptable where the source document specifies a local timezone. Normalizing a surface date format like "03/04/2025" into "2025-04-03T00:00:00Z" needs to happen at extraction time. Pushing that normalization downstream means every consumer of that data has to guess the source format independently, and they won't all guess the same way.

Enums close the remaining gap. Any field with a fixed set of valid values, like an invoice status, should be constrained with the enum keyword. "status": "approved" is both easier to read and impossible to pollute with an out-of-vocabulary value, because validation rejects it before it ever reaches a downstream system.

Naming conventions round this out. Pick camelCase or snake_case and use it everywhere. Mixed conventions in one schema are a constant, low-grade source of integration bugs. Boolean fields read more clearly with a verb prefix, like isVatApplicable or hasLineItems, so the true/false meaning is obvious without opening the documentation. Arrays should be named in the plural and scalars and objects in the singular, so a reader can tell a field's shape from its name alone. And abbreviations like desc or qty save almost nothing at scale, since JSON is gzip-compressed in transit and gzip already exploits repeated field names. What abbreviations do cost is clarity, for every developer who has to read that field name cold, for years.

The envelope pattern and the version boundary flat schemas break at

Returning a bare root array or a flat key-value object is a decision that can't be undone later without a breaking change. The envelope pattern costs almost nothing to set up at the start and avoids forcing a new API version every time the schema needs new metadata.

Adding a new field to a JSON object is safe for every existing consumer, but removing or renaming a field breaks all of them at once. A schema should be designed around that asymmetry from the first version, not discovered the hard way after the first breaking release.

The envelope pattern wraps results in a top-level object with a data key and a meta key, something like {"data": [...], "meta": {"total": 42, "warnings": []}}. That structure means pagination counts, extraction warnings, processing metadata, and confidence summaries can all be added later without restructuring anything that already exists. For document extraction specifically, the meta block is the natural home for page count, document type classification, a processing timestamp, and an overall confidence roll-up, the kind of information routing logic needs but that should never get mixed in with the actual extracted field values.

A schema that returns invoice_number and total_amount today will likely need to carry per-field confidence scores, bounding box coordinates, and review flags tomorrow. A flat structure forces a rewrite when that day comes. An envelope makes the addition just that: an addition.

Teams building extraction pipelines on grammar-constrained decoding should also check the platform limits they're working within. OpenAI's Structured Outputs feature, as a known constraint worth verifying against current documentation, caps schemas at 100 object properties total across up to 5 levels of nesting, requires all fields to be marked required, and rejects conditional keywords like allOf and not. Schema design has to stay inside those bounds whenever the extraction layer relies on constrained sampling, which makes the case for modular sub-schemas even stronger.

How to model tables in production document pipelines

A table flattened into prose or a plain list of strings is noise, because a table cell's meaning depends entirely on its row and column position, and flattening throws that position away.

Every row in a table schema needs a type. Header rows and data rows carry different semantics, and treating them the same produces a model that reads a data value as though it were a column label, or the reverse. Each cell should also carry its own bounding box coordinates alongside its text. Bounding boxes are what let an extraction model tell a header row from a data row and recover the correct structure when a row spans multiple columns or a cell wraps across lines.

This comes with a real tradeoff in verbosity. A table with many rows and columns produces a large JSON object, and across a dataset with thousands of tables, that adds up in file size and parsing time. Two mitigations handle most of it: gzip compression, and line-delimited JSON, or JSONL, which lets large extraction outputs stream through a pipeline without loading the entire document graph into memory at once. If a table exceeds the output token limit, the output gets cut off without any signal that truncation happened. The schema-level fix is to break large tables into column groups, or process them page by page and reassemble the pieces in the envelope's data array.

Accounts payable is where this matters most commercially, because line-item tables carry the numbers that actually get paid. Wrong row boundaries produce wrong totals. Wrong column-type assignments produce tax calculation errors that surface weeks later in a reconciliation. The schema for line items has to enforce row type, represent column headers as a typed sub-object, and require numeric types on quantity and unit price fields, because a float where an integer belongs, or a string where a number belongs, is exactly the kind of error that passes a shallow check and fails an audit.

Embedding confidence metadata in the schema so routing decisions have something to act on

Confidence scores that live outside the schema, returned as a separate metadata blob or not returned at all, can't drive per-field routing decisions. Per-field routing is the only granularity that actually matters once a pipeline is handling real volume, because a document is rarely wrong all over. It's usually wrong in one place.

The better design puts confidence directly into the schema as a sibling property on each field: {"invoice_number": "INV-2024-0042", "invoice_number_confidence": 0.97}, or as a nested object, {"value": "INV-2024-0042", "confidence": 0.97, "bbox": [...]}, which is the stronger pattern when bounding box coordinates are also needed. A document-level confidence score hides exactly the variance that matters: a document where nine fields extracted at 0.99 and one extracted at 0.41 looks fine in aggregate and is a real problem at the field level, maybe the one field that determines a payment amount.

Confidence bands are a useful starting point for routing, though they depend heavily on the field and the domain. High-confidence extractions, generally those clearing the upper band, can usually pass straight through. A mid-band, roughly 0.80 to 0.95, is where most teams route to human review, since this is the zone where a model's confidence and its actual correctness start to diverge. Below that, manual handling is usually the safer default. These aren't fixed rules, they shift by field criticality and by document type, but they give a pipeline somewhere concrete to draw the line.

MISCALIBRATION|Miscalibration is the cause behind all of this: confidence scores that don't track actual correctness produce routing decisions that send errors to the wrong place. A high confidence score from a vision model means nothing when the model hallucinated the value. Confidence needs to be calibrated and traceable back to pixels on the page, not just inferred from token probability. In practice, numeric fields tend to be well-calibrated, while free-text fields show overconfidence at high predicted probabilities; a free-text field reporting 0.95 deserves more scrutiny than a numeric field reporting the same number.

Confidence must therefore be designed into the schema from the start. Invofox builds its extraction output around field-level confidence for exactly this reason, pairing each extracted value with its own score so that routing decisions and its per-field accuracy guarantees can both be made against the same data, rather than against a single aggregate number that hides where the risk actually sits.

Per-field accuracy against ground truth as the only valid evaluation

A schema design can't be judged correct in the abstract. It has to be measured by per-field extraction accuracy against manually verified ground truth, on documents drawn from the real production mix, including the hardest cases, not the clean samples that make a demo look good.

Document-level accuracy hides exactly the variance that matters commercially. A document where every field is right except one critical financial figure scores well overall and fails in practice, because that one wrong figure is the one someone pays or disputes. The unit of evaluation has to be the field, not the document. Building ground truth means pulling a sample from the actual production mix, manually verifying each extracted value against the source document, and treating the lowest-scoring fields as the priority list for schema and description refinement.

Two metrics do complementary work here. Weighted Overall Accuracy (WOA) awards partial credit through continuous per-field similarity scores across all entity types, so a near-miss still counts for something. F1 applies a binary per-field precision and recall framework, counting a match as correct or not based on a matching criterion like token overlap or exact match. Both numbers matter because WOA can overstate how useful a result actually is in practice, while F1 can understate correctness when a value is semantically right but formatted differently than the ground truth. Field-type-specific comparison keeps both metrics honest: string fields compared by character-level similarity, numeric fields compared within a tolerance band, date fields compared by calendar equivalence rather than string match, so a formatting difference between source and schema doesn't get counted as an error it isn't.

The loop this creates is the real payoff. Fields that score below threshold point directly at what to fix: an ambiguous description, a type constraint with a gap, or a field whose position on the document is confusing the model. Revise, then re-test against the same ground truth, so the schema improves in measurable steps.

This is what turns a schema into something a business can actually commit to. A schema that has been evaluated per field, refined against its own failures, and re-tested against ground truth is a document precise enough to support an accuracy promise, not just a benchmark claim. That precision is why extraction APIs like Invofox tie per-field performance guarantees to the schema itself instead of to generic model benchmarks: the schema is the exact specification the extraction engine has to satisfy, which makes it measurable. Invofox's "Perfect Docs Guaranteed" offer is built on that same logic, guaranteeing accuracy per field against ground truth and charging only for documents extracted correctly. For a team choosing between a general-purpose document AI service and an API built around field-level guarantees, that distinction, a benchmark claim versus a measurable, per-field production commitment, is the one worth checking before signing anything.