Notes on typing JSON.
Short essays on the decisions behind the inferred types this site produces. Opinionated, specific, and occasionally wrong.
- 01
Nullable or optional: pick one
A nullable field and a sometimes-absent field are different promises. Collapsing them into one optional type loses the signal the server was trying to send.
- 02
When string is a lie
A field that is always "customer" is not a string. It is a discriminant. Widening it to string removes the reason the type existed.
- 03
Zod vs types: when the runtime cost earns its keep
Zod ships 14 KB of JavaScript and spends CPU on every parse. The question is not whether that is acceptable, but where the spend actually buys you something.
- 04
Go struct tags: explicit beats clever
The explicit per-field json tag looks verbose until you need to audit, grep, or change it. Then it becomes the reason the struct is still readable.
- 05
Why we do not re-infer from JSON Schema
A schema is what they promised. A sample is what they sent. Both are useful. Conflating them hides the places they disagree, which are the places that matter.