How do you write a recursive type alias for a nested JSON value, and why does the direct form fail?

### Why the obvious spelling explodes Consider a video-metadata extractor that reads whatever the container format hands back: a nested blob of scalars, lists and dicts. The honest type is recursive: ```python Json = None | bool | int | float | str | list[Json] | dict[str, Json] ``` This raises `NameError: name 'Json' is not defined` at import time. An alias assignment is an ordinary statement: Python evaluates the whole right-hand side first, and by the time it reaches `list[Json]` the name is still unbound. Nothing about type hints changes that -- the failure is plain name resolution, not the type system. Note that the lazy annotations of **Python 3.14** (PEP 649) do not save you here. They defer the evaluation of *annotations* -- what follows a colon in a signature or class body. An alias assignment is not an annotation; its right-hand side still runs eagerly. ### The two spellings that work **Quote it.** Making the value a string turns it into a forward reference. The checker parses and resolves it once every name is known; at runtime the alias is simply a `str`, and nothing is evaluated at all: ```python Json: TypeAlias = "None | bool | int | float | str | list[Json] | dict[str, Json]" ``` This works on every version that has `typing.TypeAlias` (**3.10**+) and is what you will find in codebases that must support older interpreters. **Declare it with the `type` statement** (**Python 3.12**, PEP 695). The value of a `type` statement is evaluated lazily, so a recursive reference resolves on demand and no quoting is needed. That is the modern spelling for new code; the object it creates and its parameter syntax are a topic of their own. Either way, recursion is understood by the *checker*. The interpreter has no concept of a recursive type; it holds a string, or a lazy object it never has to look inside. ### Living with the alias A recursive union is honest, and it is unpleasant to consume -- which is the senior half of this question. Every read of a `Json` value faces a seven-member union, so the checker demands narrowing before you can index, iterate or do arithmetic: ```python def duration_of(meta: "dict[str, Json]") -> float: value = meta.get("duration_s") return float(value) if isinstance(value, (int, float)) else 0.0 ``` Written across an entire extractor, that narrowing dominates the code. Three practices keep it tolerable: * **Keep the recursive alias at the boundary.** Use it for the raw payload, then parse into concrete shapes -- a `TypedDict` for known keys, a dataclass for anything with behaviour -- as soon as you know which shape you have. Downstream code then works with something narrow and checkable. * **Alias the common sub-shapes.** `JsonObject = "dict[str, Json]"` and `JsonArray = "list[Json]"` read far better in signatures than repeating the union. * **Resist `dict[str, Any]`.** It is the tempting alternative and it silently switches checking off for the whole subtree; the recursive alias at least forces the narrowing to be visible. Two operational notes are worth having ready. **Circular imports.** Shared aliases attract them: the extractor imports the alias module, the alias module imports a model for one of its members, and that model imports the extractor -- a circular import at startup that only shows up on the real entry point, not in the unit that first imported it. Keep the aliases in a leaf module with no runtime dependencies, and where an alias genuinely needs a heavy import, guard it under `typing.TYPE_CHECKING` and quote the alias so the name is never needed at runtime. **Cost.** None of this affects memory or speed. An extractor holding a 2.4 GB working set of parsed metadata pays exactly the same whether the payload is typed as a recursive alias, as `dict[str, Any]`, or not annotated at all -- the alias is a string or a lazy object, and the values are the same dicts and lists either way. Typing choices here buy checker coverage and reviewer clarity, never runtime behaviour, and a candidate who claims a performance effect has misunderstood what an alias is.