VereskLearn

Module 5 · Writing the answer

Lesson 5.3

Structured output with a schema

A schema is a written shape for the reply, so code can read the answer without guessing.

Lesson 34 of 622 min read

The problem

Why it matters

Without it

The model replies in free text. Code cannot tell where the answer ends or whether the source list is present.

With it

The model replies in a fixed shape with named fields. Code checks each field before it uses the reply.

How it works

  • The schema names each field and its type

    A schema lists each field, its type, and its meaning. Here answer is text, sourceIds is a list, and escalate is true or false. The model is asked to reply with exactly these fields.

    FieldTypeExample value
    answertext5 to 7 days
    sourceIdslist of textfaq-12
    escalatetrue or falseno, as text
    The three fields of one reply. The example reply breaks the escalate type.

  • JSON.parse turns text into an object

    The model replies with text. JSON.parse reads that text and returns an object, so code can read each field by name. If the text is not valid JSON, the call throws an error.

    1. Reply text
    2. JSON.parse
    3. Object
    4. Field checks
    From the reply text to the field checks.
    const reply = '{"answer":"5 to 7 days","escalate":"no"}';const data = JSON.parse(reply);console.log(data.answer);console.log(typeof data.escalate);

    Output

    5 to 7 days
string

  • Each field gets a type check

    The check uses typeof for text and booleans, and Array.isArray for lists. The escalate value is text, so it fails the boolean check. The function returns the names of the wrong fields.

    • answertext, ok
    • sourceIdslist, ok
    • escalatetext, not boolean
    Each field of the example reply and its result.
    function findWrongFields(data: Record<string, unknown>) {  const wrong: string[] = [];  if (typeof data.answer !== "string") wrong.push("answer");  if (!Array.isArray(data.sourceIds)) wrong.push("sourceIds");  if (typeof data.escalate !== "boolean") wrong.push("escalate");  return wrong;}const reply = { answer: "5", sourceIds: [], escalate: "no" };console.log(findWrongFields(reply));

    Output

    [ 'escalate' ]

  • A fixed reply passes the check

    Changing escalate to false gives a boolean, so the check passes. Zero wrong fields means the reply has the right shape. It does not prove the content is right, so the sources must still be checked.

    Reply as sent

    • escalate: no, as text
    • 1 wrong field

    Reply after the fix

    • escalate: false
    • 0 wrong fields
    The example reply before and after the fix.

Full code

Read the program

See the full code

Common mistakes

What goes wrong

  • Trusting the reply without a check. A model can return a wrong type or leave a field out.
  • Using a deep shape. Each extra level gives the model another chance to get a field wrong.
  • Retrying with no change. Send the list of wrong fields back to the model before a second try.

Use it when and skip it when

Is it the right tool?

Use it when

  • Code uses the reply, for example to show a source list or to route the case.
  • Every reply needs the same fields.

Skip it when

  • The reply is only shown to a reader as plain text.

Words to know

Terms in this lesson

Schema
A written description of the fields a reply must have, and their types.
JSON
A text format for objects, lists, and simple values.
Parse
Turn text into a value that code can read.
Type
The kind of value a field holds, such as text, a number, or true or false.
Full code