StoryboardAI Engineering

Structured output

Getting a reply in a fixed shape that code can read, checking it, and retrying when it is wrong.

What is structured output?

People read sentences. Software needs named fields with predictable values. Structured output means asking the model to reply in an exact shape, usually JSON, so the next piece of code can use it directly.

Because the model writes by weighted chance, the shape is occasionally wrong: a missing field, a value outside the allowed list. So your code always checks the reply before using it, and when the check fails, sends the error back and asks again.

Many providers can also enforce a shape you supply, which removes most of these failures. Checking is still worth keeping, because a reply can have the right shape and the wrong content.

The same reply as prose and as a form.Free text: "Sure! It looks like a return..."; Different wording every time; Code cannot rely on it. A fixed form: kind: return; item: blue jacket; order: (empty); Code reads it directly.Free text"Sure! It looks like a return..."Different wording every timeCode cannot rely on itA fixed formkind: returnitem: blue jacketorder: (empty)Code reads it directly
The same reply as prose and as a form.

Why does structured output matter?

A person can read a paragraph. A program cannot, reliably. The moment a model's reply has to be used by code, to fill a database, call a tool or drive a screen, it must arrive in a fixed shape. Structured output is what lets a model become a dependable part of a larger system.

How does structured output work?

  1. You define a form: the fields you need, their names and what kind of value each holds.
  2. The form is sent with the call, and the model is told to reply with it filled in and nothing else.
  3. Many providers can enforce the form, so the reply is guaranteed to have exactly those fields.
  4. Your code checks the values make sense, such as a date being real, and asks again if they do not.

When should you use structured output?

Use it when

  • A program will read the reply
  • Pulling facts out of documents or messages
  • The model must choose from a fixed set of options

Think twice when

  • A person will read the reply as prose
  • You want the model to reason freely before deciding. Let it think first, then fill in the form

Where does structured output sit in a real system?

The form is defined in your code and travels with the request. The check on the returned values runs in your code straight after the reply, before anything acts on it.

What goes wrong with structured output?

  • Trusting a form because it has the right shape. A field can be well formed and still wrong.
  • Making every field required, so the model invents a value when the page has none. Allow empty.
  • Asking for a form and an explanation in one reply, and then failing to read either.

What does structured output look like in practice?

A customer writes "I'd like to send back the blue jacket I got last week, it's too small". The model returns: kind is return, item is blue jacket, reason is too small, order number is empty. Code sees the empty field and asks the customer for it.

Watch it happen

These stories show structured output at work, one step at a time.