Measured Academy Measured Academy
Français Pilot Progress 0

Module 3 · Lesson 2 of 4

What the schema costs

  1. What happenedTyping the router multiplied input tokens several times over for the same one-word decision, while output tokens moved much less.
  2. Why it changedThe SDK turns the type into a JSON schema and sends it with every call, so each typed call carries a fixed block of extra input, and the answer comes back as a small JSON object instead of a bare word.
  3. How it is measuredInput and output tokens are logged per call from the response's usage field, then compared call by call between the untyped and typed versions of the same ticket.
  4. How to improve itLog usage per call before and after typing, keep schemas small, skip the schema where a human reads the output, and price the overhead at your own volume instead of quoting a ratio.
Explorer

The same ticket, with and without the schema

Try it. Pick a ticket and switch between input tokens and output tokens to see what typing the call added.

Where this data comes from · claude-opus-4-6, 2026-10-14; claude-opus-5, 2026-11-20

Read from the book's saved record. Nothing here is simulated.

  • runs/ch3-router-typed-2026-10-14.jsonl
  • scripts/ch3_route_typed.py
  • runs/ch3-course-route-typed-2026-11-20.jsonl
Switch

What goes over the wire

Try it. Choose the kind of type you would pass, then switch between the schema Pydantic builds and the schema that was sent.

Where this data comes from · anthropic 1.2.0, pydantic 2.13.5 · 2026-09-02

Read from the book's saved record. Nothing here is simulated.

  • runs/ch7-parse-output-format-2026-09-02.txt section A

What happened

The typed router made the same decision on every ticket. It did not cost the same.

Across ten calls Untyped, book run Typed, book run Untyped, course run Typed, course run
Model claude-opus-4-6 claude-opus-4-6 claude-opus-5 claude-opus-5
Input tokens 416 2,266 549 2,919
Output tokens 40 80 528 120
Of which thinking not recorded not recorded 488 0 on every call

Sources: BOOK.md, Measured findings, from runs/ch3-router-typed-2026-10-14.jsonl for the book's run; runs/ch3-course-route-typed-2026-11-20.txt and its BOOK.md row for the course run. BOOK.md gives the book run's input ratio as 5.4x.

Look at a single ticket and the cause is plain. For the first ticket the untyped call logged 39 input tokens and the typed call 224. For the last, 45 and 230. The tickets differ in length by a few tokens. The gap between the two versions does not move.

Why it changed

When you pass a type to messages.parse, the SDK does three things: it builds a JSON schema from the type, sends that schema along with your prompt, and builds an object of your type from what comes back. The middle step is the cost. The schema travels with every call, whether the ticket is one line or twenty.

BOOK.md puts the overhead at about 185 extra input tokens per call for this schema on the book's run, and about 237 on the course run. It is a fixed block, not a percentage, which is why the ratio looks so large here: the untyped prompt was tiny to begin with. The block grew a little on the newer model; the schema did not change.

Output grew for a simpler reason. The untyped call answered with a bare word, logged as 4 output tokens for the first ticket. The typed call answered with a small JSON object holding that word, logged as 8.

Untyped call Typed call
Sent prompt prompt plus the schema
Returned a word a JSON object with one field
Grows with the ticket the ticket, plus a constant for the schema

On the current model the output side turned round. The untyped calls thought before answering, and most of their output was thinking. The typed calls reported no thinking at all and wrote the same small object every time. So on this run the typed version spent more on input and less on output than the untyped one. That is one run of ten tickets; it is a reason to measure your own calls, not a rule that typed calls do not think.

Use the first explorer above to check this yourself, ticket by ticket, on either run. The second shows what the SDK actually sends for each kind of type it accepts.

How it is measured

  • Usage per call, from the response. Every call's usage.input_tokens and usage.output_tokens go into the run file with a label. Nothing is estimated from string length.
  • Paired by ticket. The comparison is the same ticket through both versions, so the only thing that differs is the schema and the instruction it replaced.
  • Totals from the records. The book's run logged usage for 20 of the 21 calls it made: 2,682 input and 120 output tokens, which COST.md prices at $0.02. The repeat on 2026-10-14 logged the same 2,682 input tokens. The course run on the current model cost $0.03 for the same twenty calls with usage (BOOK.md, Measured findings).

The missing call is the deliberate truncation in Lesson 3. When a call raises there is no response to read usage from, on either run. The course harness still gives it a row, with its usage left empty rather than guessed.

A caution on the ratio: it comes from one run of ten tickets with a very short prompt. With a long prompt the same fixed overhead would be a much smaller share. Quote the per-call overhead with its schema, not the ratio.

How to improve it

  • Log usage before you type anything, so you have a baseline to compare against.
  • Keep the schema small. Every field, description and nested model is input on every call.
  • Do not type what a human reads. A summary or a chat reply gains a validation step and a schema's worth of tokens for nothing.
  • A single free-text field buys nothing. The chapter notes that a bare string type sends a schema that says only "string".
  • Price it at your volume. The overhead is small per call and constant. Whether it matters is a question about how many calls you make, which Module 13 takes up.

The accepted types and the reasoning behind the recommendation are in Chapter 3 of the book, "The concept" and "The tradeoff". Next: three ways a typed call ends badly.

Every number in this lesson, and the file it came from (26)
ValueFile in the book's recordConditions
416BOOK.md
2,266BOOK.md
549runs/ch3-course-route-typed-2026-11-20.txt
2,919runs/ch3-course-route-typed-2026-11-20.txt
40BOOK.md
80BOOK.md
528runs/ch3-course-route-typed-2026-11-20.txt
120runs/ch3-course-route-typed-2026-11-20.txt
488BOOK.md
0BOOK.md
5.4xBOOK.md
39runs/ch3-router-typed-2026-10-14.jsonl
224runs/ch3-router-typed-2026-10-14.jsonl
45runs/ch3-router-typed-2026-10-14.jsonl
230runs/ch3-router-typed-2026-10-14.jsonl
185BOOK.md
237BOOK.md
4runs/ch3-router-typed-2026-10-14.jsonl
8runs/ch3-router-typed-2026-10-14.jsonl
20COST.md
21COST.md
2,682COST.md
120COST.md
$0.02COST.mdclaude-opus-4-6, Opus rates in COST.md
2,682COST.mdthe 2026-10-14 repeat on Python 3.12.3
$0.03BOOK.mdclaude-opus-5, 2026-11-20, Opus rates in COST.md

Reference: Chapter 3, "The concept" and "The tradeoff".