HASZB_AIHASZB_AI

Search across courses, lessons, glossary terms, prompts and tools.

Menu

Stage 3 · Prompt Engineering

Structured output you can rely on

Prose is for people. When something else has to read the answer, you need a shape you can parse — and a plan for when it breaks.

7 min read

In this lesson

  • Ask for output in a machine-readable shape
  • Specify a schema precisely enough to be parsed
  • Handle the cases where structure is not honoured

As soon as anything other than a human reads the output — a script, a database, another step in a workflow — prose becomes a liability. You need a shape.

Name every field

"Return JSON" is not a specification. This is:

Return only a JSON object with these fields:

  • title (string): the headline, verbatim
  • published (string or null): ISO date YYYY-MM-DD, or null if not stated
  • topics (array of strings): at most three, lower case
  • confidence (number): 0 to 1

No text before or after the JSON.

Every field has a name, a type and a rule. published has an explicit null case. topics has a cap and a casing rule. The last line handles the most common annoyance — a friendly sentence wrapped around the JSON that breaks your parser.

Always give "I don't know" a home

This is the highest-value line in this lesson. A model completes plausible text. If your schema has a price field and the document contains no price, the most plausible completion is a price, because that is what the field is for.

Add an explicit escape — null, "unknown", an empty array — and say when to use it. You are not making the model more honest; you are giving the honest answer a legal shape to arrive in.

Plan for it breaking

Even with a good schema, output occasionally arrives malformed — truncated because it hit a length limit, wrapped in a code fence, or with a trailing comma. Treat parsing as something that can fail:

  1. Validate, do not trust. Parse into a schema and check the types. Never feed unvalidated model output straight into something that acts on it.
  2. Retry once, with the error. Handing back "that was not valid JSON: unexpected end of input" fixes a large share of failures.
  3. Have a fallback. Decide in advance what happens on a second failure. Surfacing an honest error beats storing a broken record.

Length limits truncate structure

A response that runs into the output limit stops mid-token, which for JSON means an unclosed brace and a parse error. If you are seeing intermittent truncation, the cause is usually a schema that is too large for the room you gave it — cap array lengths, split the work, or raise the limit.

When not to bother

If a person is reading the answer, structure often makes it worse. Forcing a nuanced explanation into rigid fields strips exactly the qualifications that made it useful. Use structure when something downstream needs to parse it. Use prose when a human needs to understand it.