Escape hatch for recursive schemas where type-level inference
cannot proceed. Typed as a map from field name (any string except
the brand key) to FieldOverride, branded with a required
discriminator so the unsafe path is an explicit opt-in rather than
a silent default.
Earlier revisions made the brand optional (__unsafe?: true).
That defeated the brand's purpose: any plain
Record<string, FieldOverride> literal silently satisfied the type
and the "unsafe" intent was invisible to readers and reviewers.
Marking the brand required forces callers to write
{ __unsafe: true, ... }, making the escape-hatch use visible at
the call site.
The brand key is carved out of the field-name index signature so
__unsafe: true does not collide with the FieldOverride value
constraint — an index signature [string]: FieldOverride would
otherwise reject the boolean literal.
JSDoc trade-off note: This bypasses field-level type safety.
Prefer restructuring the schema to avoid deep $ref chains
when possible.
Escape hatch for recursive schemas where type-level inference cannot proceed. Typed as a map from field name (any string except the brand key) to
FieldOverride, branded with a required discriminator so the unsafe path is an explicit opt-in rather than a silent default.Earlier revisions made the brand optional (
__unsafe?: true). That defeated the brand's purpose: any plainRecord<string, FieldOverride>literal silently satisfied the type and the "unsafe" intent was invisible to readers and reviewers. Marking the brand required forces callers to write{ __unsafe: true, ... }, making the escape-hatch use visible at the call site.The brand key is carved out of the field-name index signature so
__unsafe: truedoes not collide with theFieldOverridevalue constraint — an index signature[string]: FieldOverridewould otherwise reject the boolean literal.JSDoc trade-off note: This bypasses field-level type safety. Prefer restructuring the schema to avoid deep $ref chains when possible.