Field Descriptions Are Prompts: Writing Schemas the Model Can Follow

The schema does two jobs at once

A field schema is usually introduced as a contract: it fixes the names, types and shape of the JSON you get back, so downstream code can rely on it. That is true and it is only half the story. The same schema is also the instruction set the generative model reads while it works. Every field name, every description and every enumerated category is text the model sees.

Holding both jobs in mind changes how you write schemas. A contract wants terseness and stability. A prompt wants specificity and context. When the two pull in opposite directions, the prompt usually wins, because a stable contract full of wrong values is worse than useless.

Descriptions carry the real information

The single highest-leverage habit is writing descriptions that tell the model where to look and what the value looks like. Say that an invoice date usually sits at the top right, that it may be labelled as a billing date or an issue date, and that it typically appears in day-month-year or month-day-year form. That description does more for accuracy than any amount of restructuring.

Three refinements follow from the same idea. List the aliases a field goes by, because real document sets label the same concept several ways and the model cannot guess your synonyms. Describe what the field is rather than what it is not; negative definitions read clearly to humans and poorly to models. And write names and descriptions in the language of the content — an Italian invoice deserves Italian field names, because a language mismatch measurably hurts accuracy.

There is a hard limit here worth knowing: a description can run to about a thousand characters, and a field name to sixty-four. That is generous for a good description and tight for a bad one.

Choose the method deliberately

Each field can carry a method that says how the value is produced. Extract takes the value as it appears in the content, which suits invoice numbers and dates. Classify picks from a fixed list of categories, which suits document type or sentiment and pairs naturally with an enumerated set. Generate produces a value by inference or summarisation, which suits risk ratings, summaries and anything not written down anywhere.

If you omit the method, the service infers one from the type and description. Convenient, but vague; being explicit is the recommended habit, and it forces you to think about whether the value is really present on the page.

One constraint decides many exam questions: extract is only available for document analyzers. Audio, video and image analyzers can generate and classify, and nothing else. If you find yourself designing an extract field over a call recording, the schema is wrong before it runs.

Shape the data with real types

Repeated data should be modelled as an array of objects, not as a string field whose description begs the model to emit JSON. Invoice line items are the canonical case: an array whose items are objects with a description, a quantity, a unit price and a total. You get typed values, they are counted properly against limits, and downstream code does not have to parse a string that may not parse.

Nesting is supported through object and array types, but keep it shallow. Beyond two or three levels, both performance and extraction accuracy suffer. The practical limits are roomy — up to a thousand named fields, and up to three hundred categories in total across classify fields — but a schema anywhere near those numbers is usually a design problem rather than an ambitious one. Note how fields are counted: a list of strings counts as one field, while a group with two subfields counts as three.

Supported typed values such as dates and numbers come back normalised to a canonical form. Normalisation is not configurable, and the normalised value is the value you receive, so do not write assertions expecting the exact characters printed on the page.

Improving a schema that underperforms

When results disappoint, the ordering of remedies matters. Refine the descriptions first. Clear descriptions frequently fix problems that people try to solve with data, and they cost nothing but thought. Only then consider adding labeled example documents to a knowledge base, and when you do, cover each distinct layout you need to handle rather than adding several examples of the same template.

Measure before and after. Test extraction on a representative set of files, add examples, then test again on the same set. Without that discipline you cannot tell whether training improved the analyzer or merely changed which fields it gets wrong.

Two habits worth unlearning

The first is defining fields for content the analyzer already returns. Transcripts, recognised text and video key frames arrive in the output by default; asking for them again as fields spends model tokens to duplicate what you have. Define a field only when you need something further done to that content, such as a summary or an entity list.

The second is treating the schema as fixed forever because it is a contract. Schemas are cheap to revise and expensive to get right the first time. Expect to iterate on descriptions in the same way you would iterate on a prompt.