Structured output

What it isCopy Anchor Link

Structured output means the model returns JSON that matches a schema you define. Providers offer this through schema-constrained generation or through tool calls whose arguments are the schema. Libraries add a validation step and retry the call with the error message when validation fails.

Why it mattersCopy Anchor Link

Free text breaks parsers in small ways: a trailing explanation, a missing field, a changed key name. A schema makes the contract explicit. Validation turns silent bad data into a loud error you can count and fix. Keep schemas small, give fields descriptions (the model reads them), and use enums instead of free strings when the set of values is known.

A worked example: a schemaCopy Anchor Link

Schema: name (string), years_experience (number), skills (list of strings), seniority (one of junior, mid, senior). Prompt: "Extract these fields from the resume." The model returns {"name": "Maya Lin", "years_experience": 5, "skills": ["Python", "SQL"], "seniority": "mid"}. Your code validates it. If seniority came back as "intermediate", validation fails and you retry with the error message.

TipsCopy Anchor Link

Use enums for fixed choices. Make fields optional when the information may be missing, so the model is not pushed to invent a value. Describe each field in one sentence. Log every validation failure and read them weekly.

How the constraint worksCopy Anchor Link

With schema-constrained generation, the system filters the model's choices at every token. The model scores all possible next tokens, and the system removes those that would break the schema. After {"years": only digits are allowed. After "seniority": only the start of junior, mid or senior is allowed. The model picks among what remains. The result always has a valid shape. It is not guaranteed to hold the right value.

Valid is not correctCopy Anchor Link

Suppose the resume says 15 years and the model returns 5. The JSON is valid, validation passes and the data is wrong. Another case: a resume with no seniority stated, and the model picks "mid" because the schema forced a choice. The symptom is no errors but bad data. To confirm, sample 20 outputs, compare each field with the source by hand, and compute accuracy per field.

Trade-offs in schema designCopy Anchor Link

A schema that is too strict forces an invented answer. Add an "unknown" option to enums and make uncertain fields optional. Deeply nested schemas fail more often, so flatten them when you can. If you ask for only a final answer, you may lose the benefit of thinking first. A common fix is a "reasoning" field placed before the "answer" field, so the model writes its working before it commits.

Try it yourself: five messy emailsCopy Anchor Link

Collect five event emails. Write a schema with four fields: name, date, place and a type chosen from a fixed list. Ask a chat model to fill it for each email and check the JSON in any free online validator. Count how many are valid and how many are correct. Expect most to be valid and a few wrong, usually dates written in an unusual way.

Common mistakeCopy Anchor Link

Asking for JSON in prose and then parsing with string tricks. Use the provider's structured output feature or a validation library.