Signal & Context
← Back to the reading room

Engineering

A JSON schema defines the handoff

Structured generation helps software accept an answer. Domain checks must still establish that its values are supported and its proposed actions are allowed.

On this page

Define what the receiving application expects

An extraction workflow becomes easier to operate when its output has an explicit shape. A record might contain a document identifier, a proposed category, supporting evidence and a disposition. The receiving application can check those fields before writing a database row. That removes ambiguity from the handoff while leaving the factual assessment visible as separate work.

The official JSON Schema object guide explains properties, required fields and controls on additional properties. These are useful tools for describing a contract. Declaring a property does not by itself require its presence, and accepting an object does not imply that every value inside it matches the source document.

Inspect the validator and generation mechanism

Schema dialect and implementation behavior matter. The 2020-12 validation specification distinguishes format annotation from format assertion. A team using that dialect should check its validator configuration before assuming that a field marked as an email or URI receives the intended format validation. Newer dialects and specific implementations may make different choices.

The llama.cpp grammar guide describes constrained generation and conversion of a subset of JSON Schema into its grammar format. The word subset has practical consequences: confirm that the particular constraints in your contract are supported. A schema file accepted by one part of a stack does not demonstrate identical enforcement throughout the stack.

Give missing information a valid representation

Consider a hypothetical receipt extractor asked for a tax amount that is absent from the document. If the contract requires a number and provides no representation for missing evidence, the application creates pressure to return a plausible value. A clearer design can distinguish an observed value from missing or uncertain information, with an evidence reference for the observed case.

That is our design recommendation, not a benchmark finding about a particular model. The appropriate representation depends on the receiving system: an explicit status field, an optional value or a separate review disposition may work. Document the meaning so a missing amount cannot silently become zero in a later calculation.

After structural validation, apply domain checks tied to the task. Does the document identifier refer to a source the caller may access? Does the cited span actually support the extracted value? Are units and currencies compatible with the operation? A syntactically valid URL also needs a separate destination policy before software follows it or sends data to it.

Make failure observable and bounded

Record whether a failure came from parsing, schema validation, unsupported constraints, missing evidence or a domain rule. That distinction helps developers improve the right component. Sending every rejected record back to the model with a generic request to try again can hide recurring source problems and make operating costs harder to explain.

If a retry is appropriate, bound it and preserve the initial failure. Prevent repeated attempts from creating duplicate records or external actions. Route unresolved cases into an explicit review state rather than coercing them into an accepted object. The software boundary should remain understandable even when the model cannot complete the task.

A well-designed schema makes integration more dependable because it gives the application something precise to validate. Pair it with source checks, domain rules and clear failure states, and the structured answer becomes a useful intermediate record whose meaning the rest of the system can trust appropriately.

Suggest a correction

Continue reading