LESSON 02 OF 05 · 14 MIN

Structured Model Interfaces

Ask the AI to fill in a form, not write you a paragraph you then have to unpick.

Imagine asking a colleague for someone’s contact details. They could write you a friendly paragraph — "I think Sam is on the second floor, you could try emailing them, their address is probably the usual format". Or they could fill in a card: name, email, phone. The card is boring. The card is also the one you can act on without guessing.

So what is this really about?

The same is true when you ask an AI for something your code has to use. If you ask for a paragraph, you then have to pick it apart and hope you got it right — and you will be wrong eventually, quietly, on a phrasing you never tested. Ask for the card instead: decide the exact fields you need first, then ask for those.

A schema is defined first; the model fills it in, and the result is checked against that schema before anything uses it.

QUICK CHECK

The AI returns a properly formed card, but one required field is missing. Why is this more dangerous than a completely broken answer?

The words you will hear

Structured output: The filled-in card. Named fields, not a paragraph you have to interpret.
Schema: The blank card. What fields exist, which are required, what values are allowed.
Parsing: Picking apart text to find the bits you wanted. Necessary with paragraphs, avoidable with cards.
Validation: Checking the card is properly filled in before you use it — even when it looks fine.

What you will be able to do

Define an explicit output schema before writing a prompt.
Handle a response that does not match the schema without crashing.
Explain why parsing free text is a design failure rather than a parsing problem.

Going deeper

The single highest-leverage change in most AI codebases is to stop asking the model for text and start asking it for data.

Free text forces you to write a parser for output that has no contract. It will work for the cases you tried and break on the first response that phrases things differently — and it will break silently, producing a plausible wrong value rather than an error.

Schema first, prompt second

Decide the shape before the wording. Writing the schema first forces the questions that matter: which fields are genuinely required, what are the allowed values, and what should happen when the model does not know. A field like confidence is only useful if you have decided in advance what you will do with a low one.

Keep the schema as small as the task allows. Every optional field is a branch you have to handle, and a model given fifteen fields will fill all fifteen whether or not it has grounds to.

The response is untrusted input

A structured response is still a response from a remote service that can fail. Three things must be handled explicitly:

It does not parse. The output is not valid JSON, or is wrapped in commentary. Do not attempt repair with string surgery — retry once with the same schema, then fail cleanly.
It parses but does not conform. A required field is missing, or an enum contains a value you never defined. This is the dangerous case: the shape looks right, so unvalidated code proceeds with nonsense. Validate against the schema every time, including when the call succeeded.
It conforms but is wrong. Validation cannot catch this. It is why the next two lessons are about boundaries: a wrong value that can only be written to a draft is a small problem, and the same value wired to an irreversible action is a large one.

Where people go wrong

The common mistake is treating schema validation as a formality that passes in testing and therefore can be skipped in the hot path. It passes in testing because testing uses the inputs you thought of. Validation exists for the ones you did not.