Why can a TypedDict-annotated webhook payload still be missing a declared key at runtime?

## The scenario A ticket-triage bot receives webhooks. Its handler declares the payload shape and reads it: ```python class TicketEvent(TypedDict): id: int priority: str assignee: str event: TicketEvent = json.loads(body) route(event["assignee"]) ``` The checker is green in CI. In production the bot works for weeks, then a small fraction of events start failing. What on-call actually sees is an intermittent timeout on the triage endpoint: the handler raises `KeyError: 'assignee'` on unassigned tickets, the platform retries the delivery, and each retry lands on a cold worker that pays a 45-second cold start before failing again. The symptom looks like a latency problem; the cause is that the payload never matched the declared shape. ## Why the annotation guaranteed nothing here Two separate things are going on, and a strong answer separates them. **First, `TypedDict` has no runtime existence to enforce anything with.** The annotation is erased as far as behaviour is concerned; the value is a plain `dict`. Even the explicit constructor call validates nothing — `TicketEvent(id="T-42")` returns `{'id': 'T-42'}`, wrong type and missing keys included. And because there is no runtime class, you cannot fall back on a check: `isinstance(event, TicketEvent)` raises `TypeError: TypedDict does not support instance and class checks`. **Second, and this is the part that makes it silent, the value came from `Any`.** `json.loads` is typed as returning `Any`, and `Any` is bidirectionally compatible with every type — assigning it to a `TypedDict`-typed variable is exactly the escape hatch `Any` exists to provide. The checker is not being lax; you told it to stop looking. The same hole appears with anything returning `Any`: a `dict` read out of an untyped helper, a value pulled from an untyped third-party client, an explicit `cast`. ## What a correct design looks like Put a real boundary between untrusted bytes and the typed interior: 1. **Decode** the bytes into an unknown object. Type it as `object` rather than letting `Any` leak — that forces the next step to happen. 2. **Validate** once: confirm it is a mapping, confirm every required key is present, confirm the value types, and reject or normalise anything that fails. This is either explicit code or a runtime validation library whose job is precisely this. 3. **Describe** everything inward with the `TypedDict`. From that point on the static guarantees are real, because the data was proven to match at the one place it entered. Hand-rolling step 2 is not exotic for a flat shape — `typing.get_type_hints` hands you the declared key-to-type mapping and you loop over it. For nested or optional-heavy shapes, a validation library is the better trade. Either way the important architectural point is that the validation is a *separate step you wrote*, and the `TypedDict` is documentation and static checking layered on top of it. ## Diagnosing this class of bug When a shape violation reaches production, the trail is often confusing precisely because the failure surfaces far from its cause — as a `KeyError` deep in business logic, or, as here, as a latency symptom created by retries. Useful moves: log the raw payload keys at the boundary before anything reads them; make the reads that assume presence explicit (`event.get("assignee")` returns `None` instead of raising, which turns a crash into a decision); and mark genuinely optional keys `NotRequired` so the checker starts *requiring* the calling code to handle absence rather than assuming presence. That last one is a real fix rather than a silencer — it changes what the checker enforces at every read site. ## Testing that the boundary holds Because the guarantee is static, the tests that matter are the ones about the edge, not about the shape. Two are worth naming. First, feed the validator real captured payloads — including the awkward ones, such as an event for an unassigned ticket — and assert that it rejects or normalises them rather than passing them inward; a shape violation should fail loudly at the boundary, in a test, long before it becomes a retry storm. Second, keep the checker honest about `Any`: many teams turn on the strictness setting that reports an expression whose type silently became `Any`, precisely so that the assignment in this scenario shows up as a warning instead of as green CI. Neither is exotic, and together they close the gap that the annotation alone left open. ## The one-line summary to give an interviewer `TypedDict` is a claim about a dictionary, verified by a tool against the code it can see. Data arriving from outside was never seen by that tool, so the claim is only as good as the validation you put at the edge — and `Any` from a decoder will let the claim pass unexamined.