Styxis
Company
Knowledge

Pydantic Enum dictionary keys: agreeing on the JSON wire mapping

In-memory key types differ from JSON object keys. Share an explicit mapping in both directions.

Pydantic Enum dictionary keys: agreeing on the JSON wire mapping

A dictionary keyed by Enum members crosses an additional boundary when JSON turns its keys into strings. A failed reload or replacement by a default status can change the meaning of category totals. Explicitly map wire strings to original members to distinguish format conversion from semantic restoration. [1, 2, 3]

What the primary source establishes

A Pydantic report describes ordinary Enums with integer values, and non-string Literal keys, failing validation after JSON stringifies the keys. It distinguishes controls using IntEnum, string Enums, ordinary int, and other types that round-trip successfully. [1]

The handover decision

The team should record each Enum member's meaning, source value, and wire string together. Check that per-key counts survive both conversion directions. A table of enum_member, wire_key, restored_member, and count makes a decoder's fallback distinguishable from the original status. [1, 3]

A reference defined before the output

The illustrative mapping assigns wire string 200 to OK. Restoring OK is normal; replacing it with UNKNOWN fails that mapping. A decoder error must not quietly become a new status category, because the resulting status totals would mean something different from the source totals. [1, 3]

The scoped Truthound check

Truthound Core 3.3.2 provides ColumnPairInSetValidator to check prepared wire_key and restored_member pairs against approved valid_pairs. Stringifying a key and restoring its Enum meaning are separate operations. Check null-handling settings so unresolved keys do not disappear from validation. [1, 2, 3]

Limits and alternative choices

Replacing every Enum with IntEnum can change comparison semantics, so this is not a universal type-migration recommendation. Define a separate string-key JSON schema with an explicit decoder. A wire schema already using string Enums is not directly exposed to the non-string literal-key case. [1, 3]

Application conditions

Prepare the approved bidirectional Enum-to-wire mapping and retain unresolved keys in the comparison inventory.

Alternatives

Define a separate string-key JSON schema with an explicit decoder.

Limitations

  • Replacing every Enum with IntEnum can change comparison semantics, so this is not a universal type-migration recommendation.

Evidence

Event checked
Subject checked
Modified