Claude and the Anthropic SDK (TypeScript) · Chapter 9 of 21

Structured output

By the end of this chapter you can get Claude's reply as JSON that fits a schema you wrote, every time: by hand with output_config.format, and typed with zod, zodOutputFormat and messages.parse. You will let missing fields be null instead of made up, and you will know the one case a schema cannot save you from: a reply cut off by max_tokens. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Tools and structure
  • 4 tasks
  • TypeScript
  • In the all labs plan

The first 2 chapters of Claude and the Anthropic SDK (TypeScript) are free. This one comes with the all labs plan.

Why you need this

Sahay so far answers families in sentences. But Parchi's own systems need data: Kamla pastes a hospital bill into the chat, and the claims desk wants a record with the patient, the hospital, the dates, every item and the total, to file it and check it. Farhan wants the totals in a spreadsheet.

So ask Claude for JSON? Asked in words, Claude writes for a person: a friendly sentence, the JSON in a fenced block, a closing line. Your JSON.parse throws on the first character. Strip the fence with a regular expression, and the next reply names a field differently, or leaves one out. A program needs a guarantee, not a habit: the reply is JSON, and it fits the schema.

What you build: 4 tasks

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

  1. Task 1

    json-schema.ts: a schema by hand

    Send 'claude-opus-5-5' (max_tokens 1024) one user message: BILL (given), a blank line, then Extract this bill. With it send output_config.format: { type: 'json_schema', schema }, where schema is an object with patient (string), hospital (string), items (an array of objects with name, a string, and amount, an integer) and total (an integer), every field required, and additionalProperties: false on both objects.

    JSON.parse the reply's text and print PATIENT at HOSPITAL: N items, total ₹X (inr(total)).

  2. Task 2

    extract-bill.ts: typed records with zod

    Export Bill, a zod object with claim_id, patient, hospital, admitted, discharged (strings), items (an array of { name: string, amount: number }), total (number), and bill_no and doctor (strings that may be null).

    Export async function extractBill(text: string) that sends 'claude-opus-5-5' (max_tokens 1024) one user message, text then a blank line then Extract this bill., with client.messages.parse and output_config: { format: zodOutputFormat(Bill) }, and returns parsed_output (throw if it is null).

  3. Task 3

    cut-off.ts: a reply cut short

    Send BILL (given), a blank line, then Extract this bill. to 'claude-opus-5-5' with client.messages.create, output_config: { format: zodOutputFormat(Bill) } (Bill from ./extract-bill.ts) and max_tokens 100. If its stop_reason is 'max_tokens', print cut off at max_tokens 100: retrying with max_tokens 1024 and send it again with max_tokens 1024.

    Then print stop_reason: STOP, parse the text with Bill.parse(JSON.parse(text)) and print CLAIM_ID: N items, total ₹X.

  4. Task 4 · interview question

    Interview: in-words.ts

    "Why not just ask Claude for JSON in the prompt?" Send 'claude-opus-5-5' (max_tokens 1024) BILL, a blank line, then Extract this bill as JSON. with no format. JSON.parse the reply's text in a try, and print in words: NAME: MESSAGE from the error it throws (or in words: parsed if it does not).

    Then send BILL, a blank line, Extract this bill. with client.messages.parse and zodOutputFormat(Bill), and print with a format: N items, total ₹X from parsed_output.

What you will learn

  • Why "reply in JSON" in the prompt is not enough, with the error it gives.
  • output_config.format: a JSON schema the reply must fit.
  • zodOutputFormat and messages.parse: the schema written once in zod, the reply checked and typed (parsed_output).
  • Nullable fields: an honest "not on this bill" instead of an invented value.
  • The limit: max_tokens still cuts a reply, so read stop_reason first.

More in Tools and structure

Build "Structured output" yourself

Parchi, a Jaipur startup, helps families claim health insurance. You build Sahay, a claims assistant that reads bills and policies with Claude, and measure what caching, models and effort cost. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of Claude and the Anthropic SDK (TypeScript) are free. This one comes with the all labs plan.