Module 3 · Lesson 2 of 4
What the schema costs
- What happenedTyping the router multiplied input tokens several times over for the same one-word decision, while output tokens moved much less.
- 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.
- 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.
- 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.
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.jsonlscripts/ch3_route_typed.pyruns/ch3-course-route-typed-2026-11-20.jsonl
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_tokensandusage.output_tokensgo 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.mdprices 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)
| Value | File in the book's record | Conditions |
|---|---|---|
| 416 | BOOK.md | |
| 2,266 | BOOK.md | |
| 549 | runs/ch3-course-route-typed-2026-11-20.txt | |
| 2,919 | runs/ch3-course-route-typed-2026-11-20.txt | |
| 40 | BOOK.md | |
| 80 | BOOK.md | |
| 528 | runs/ch3-course-route-typed-2026-11-20.txt | |
| 120 | runs/ch3-course-route-typed-2026-11-20.txt | |
| 488 | BOOK.md | |
| 0 | BOOK.md | |
| 5.4x | BOOK.md | |
| 39 | runs/ch3-router-typed-2026-10-14.jsonl | |
| 224 | runs/ch3-router-typed-2026-10-14.jsonl | |
| 45 | runs/ch3-router-typed-2026-10-14.jsonl | |
| 230 | runs/ch3-router-typed-2026-10-14.jsonl | |
| 185 | BOOK.md | |
| 237 | BOOK.md | |
| 4 | runs/ch3-router-typed-2026-10-14.jsonl | |
| 8 | runs/ch3-router-typed-2026-10-14.jsonl | |
| 20 | COST.md | |
| 21 | COST.md | |
| 2,682 | COST.md | |
| 120 | COST.md | |
| $0.02 | COST.md | claude-opus-4-6, Opus rates in COST.md |
| 2,682 | COST.md | the 2026-10-14 repeat on Python 3.12.3 |
| $0.03 | BOOK.md | claude-opus-5, 2026-11-20, Opus rates in COST.md |
Reference: Chapter 3, "The concept" and "The tradeoff".