An Untagged Enum Chooses the First Match

An untagged enum lets a Rust program accept several JSON shapes without a variant name in the response. Serde tries its variants in declaration order and returns the first one that deserializes successfully. That makes order part of how the program interprets an ambiguous response.

Where order takes over

Consider an API that returns either a record or an error:

#[derive(serde::Deserialize)]
#[serde(untagged)]
enum Reply {
    Record { id: String },
    Failure { id: String, error: String },
}

The JSON object {"id":"42","error":"denied"} has the fields needed by Failure. It also has the field needed by Record. Serde’s untagged matching rule tries Record first. For self-describing formats such as JSON, Serde ignores unknown fields by default. The error field therefore does not make Record fail. The result is Reply::Record, with no error text in the value the program receives.

Moving Failure above Record changes the result for the same object. The JSON has not changed. The enum’s order has. That creates a fragile dependency when two variants can both accept one payload.

Why shape changes matter

Suppose an API adds a field to a response while retaining its existing fields. With default unknown-field handling, an earlier, broader variant can still accept that response. A later variant may never get a chance. Defaults on fields can widen the overlap further: Serde’s field attribute fills a missing value when #[serde(default)] is present. Review defaulted fields when deciding whether two shapes are distinct.

What to do

Prefer an explicit discriminator when the API contract allows it. Serde documents internally and adjacently tagged enums for responses that carry a variant tag. If the wire format is fixed, give each variant required fields that distinguish it. Where rejecting extra fields fits the contract, #[serde(deny_unknown_fields)] makes an unknown field an error. Serde says this attribute cannot be combined with flatten, so check that constraint before using it.

Add a deserialization test for a payload containing fields from both shapes. Assert the chosen variant, then repeat with realistic added fields. The test makes a future enum reorder or schema change visible where the response enters the program.