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

Two ways to ask for the same thing

You need a customer’s details out of a messy support message. You could ask for a description, or you could ask for a filled-in form. The difference decides how much of your code is guesswork.

Aspect	Ask for a paragraph	Ask for a form
What you get	Sentences that vary every time	Named fields, same shape every time
To use it	Write a parser and hope	Read the field
When it changes	Your parser silently gets it wrong	Validation catches it immediately
When it fails	You often cannot tell	You can tell exactly

Decide the form before the wording

Writing the shape first forces useful questions. Which fields are genuinely required? What values are allowed? What should happen when the model does not know?

YOUR TURN

You are adding a "confidence" field so the model can say how sure it is. When is that actually useful?

How many fields should your form have?

Fewer than you first think. Every optional field is a branch you have to handle, and a model given fifteen fields will fill in all fifteen whether or not it has grounds to. Start with what you will actually use.

Three ways a reply goes wrong

A structured reply is still a reply from a remote service. It fails in three distinct ways, and they need different handling.

1It will not parse. Not valid JSON, or wrapped in chatter. Retry once with the same request, then give up cleanly. Do not try to repair it with string surgery.
2It parses but is not right. A field is missing, or contains a value you never allowed. This is the dangerous one — it looks fine, so unchecked code carries on with nonsense.
3It is valid but wrong. Validation cannot catch this. Nothing can. It is why the next two lessons are about limiting what a wrong answer can do.

WHAT WOULD YOU DO?

The model returns valid JSON, but "urgency" says "extremely_high" — a value your list does not include. What do you do?

Accept it and treat it as "high" — Tempting, and it will work until the day the model invents something you cannot map. Now you are guessing on the customer's behalf.

Reject it and retry once — Right. It did not meet the contract, so it does not get used. One retry costs little; accepting invented values costs you the guarantee that the field means anything.

Store it anyway and sort it out later — Now your database contains values your code does not understand, and every future query has to handle them. Later never comes.

Ask for data you can check, not prose you have to interpret.