The Vercel AI SDK · Chapter 5 of 21

Structured output

By the end of this chapter you can get typed data out of a model instead of prose: an object that fits a zod schema, a list of them, or one choice from a set. You will describe each field so the model fills it the way you need, see the JSON schema the SDK sends, and catch a reply that does not fit. You will read Deepa's WhatsApp enquiries into objects, ask for a list of plant suggestions, and send the enquiries a model cannot fill to a person. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: The SDK on the server
  • 3 tasks
  • TypeScript
  • In the all labs plan

The first 2 chapters of The Vercel AI SDK are free. This one comes with the all labs plan.

Why you need this

Not every job for a model is a chat. Every morning Deepa opens WhatsApp to a pile of bulk enquiries: a cafe wants twelve areca palms by Friday, an office wants twenty money plants gift wrapped for Diwali, a clinic wants peace lilies "next week". Her team copies each one by hand into the order sheet: customer, pincode, area, items, date, urgency, gift wrap. It takes an hour, and a wrong pincode means a wasted trip across Bengaluru.

A model can read those messages. But Mali so far writes sentences, and a sheet needs fields. You could ask for "the customer, pincode and date" in words and then pull them out of the reply with string code, but the wording changes from one reply to the next, a date comes back as "Friday" one time and "6 Nov" the next, and nothing tells you when a field is missing. Code needs data it can trust: the same shape every time, checked.

What you build: 3 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    enquiry.ts: Deepa's inbox as data

    Export a zod schema Enquiry from enquiry.ts with customer (string), pincode (string), area (string), items (an array of { product: string, qty: number }), deliverBy (string, described as the delivery date as YYYY-MM-DD), urgency (z.enum(['urgent', 'normal'])) and giftWrap (boolean), each with a .describe() saying what it holds.

    Export an async function readEnquiry(text) that calls generateText with lab('lab-chat'), the text as the prompt and output: Output.object({ schema: Enquiry }), and returns result.output. Under if (import.meta.main), read inbox[0].text (from ../../shared/haribhari.ts) and print it.

    The Check reads all six enquiries of Deepa's inbox and compares each object with its own run: dates must come back like 2026-11-06.

  2. Task 2

    suggest.ts: a list of suggestions

    Export an async function suggest(request) from suggest.ts. It calls generateText with lab('lab-chat'), the request as the prompt and output: Output.array({ element }), where element is a zod object of name (string), price (number) and petSafe (boolean), each with a .describe(), and returns result.output (an array).

    Under if (import.meta.main), suggest for Plants for a sunny window, under ₹400 and print one line a plant: NAME, ₹PRICE, adding , safe for pets when petSafe is true.

  3. Task 3 · interview question

    Interview: needs-person.ts, when the model can't fill it

    Make a strict zod schema: customer (z.string().min(1)), pincode (string) and deliverBy (z.iso.date()), each with a .describe(). For each enquiry of inbox (../../shared/haribhari.ts), in order, call generateText with lab('lab-chat'), the enquiry's text as the prompt and output: Output.object({ schema }), and print ID: CUSTOMER, PINCODE, DATE.

    When the reply does not fit the schema, generateText throws a NoObjectGeneratedError (from 'ai'): catch it (NoObjectGeneratedError.isInstance(error); rethrow anything else) and print ID: needs a person: and error.text.

    Deepa will ask: before, W2 came back with an empty name. Why is an error better than an empty string?

What you will learn

  • Output.object({ schema }): a reply that is an object fitting your zod schema, typed.
  • What is sent: the JSON schema, and why the provider must support it.
  • .describe(): telling the model what a field holds and in what format.
  • Enums and booleans: answers from a fixed set.
  • Output.array and Output.choice: a list of objects, or one option.
  • NoObjectGeneratedError: what happens when the reply does not fit.

More in The SDK on the server

Build "Structured output" yourself

HariBhari, a Bengaluru plant shop, wants Mali, a plant helper on its website. You build it end to end, from the first call to a chat that streams cards, asks before it adds to the cart and stays within budget. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of The Vercel AI SDK are free. This one comes with the all labs plan.