Serde & Serialization

Core Question

How does this data cross the boundary between Rust types and external formats?

Every Serialize / Deserialize derive is a contract with the outside world. The shape of your Rust types becomes a wire format, a config schema, or a storage layout. Get the representation wrong and you break every consumer.

Error -> Design Question

Quick Decisions

Enum Representation Strategies

Serde supports four enum encodings. The default (externally tagged) is rarely what you want for JSON APIs.

#[derive(Serialize, Deserialize)]
enum Message {
    Text { body: String },
    Image { url: String, width: u32 },
}

Use internally tagged for JSON APIs — it matches how most languages model discriminated unions.

Use adjacently tagged when you need versioned payloads or the content can be any type.

Use untagged only as a last resort — error messages are poor and it tries variants in order.

See references/enums.md for decision matrix and forward-compatibility patterns.

The Attribute Quick Reference

See references/attributes.md for full details and code examples.

Feature-Gating Serde in Libraries

Library crates should not force serde on consumers. Use an optional feature:

[features]
default = []
serde = ["dep:serde"]

[dependencies]
serde = { version = "1", features = ["derive"], optional = true }

#[cfg_attr(feature = "serde", derive(
    serde::Serialize, serde::Deserialize,
))]
pub struct Config {
    pub name: String,
    pub timeout_ms: u64,
}

This pattern keeps the dependency tree lean for consumers who don't need serialization.

Usage Scenarios

Scenario 1: "I'm building JSON API request/response types" -> Derive Serialize + Deserialize, use rename_all = "camelCase", internally tagged enums, and deny_unknown_fields on input types. Keep response types permissive, input types strict. See references/attributes.md.

Scenario 2: "I need to parse a TOML config file into typed structs" -> Derive Deserialize, use #[serde(default)] for optional settings, nested structs for sections. Validate invariants after deserialization or in a custom impl. See references/custom.md.

Scenario 3: "My domain types differ from my wire format" -> Create separate DTO structs with serde derives. Convert between domain and DTO using From/Into. Never put serde derives on domain types directly. See references/custom.md for DTO patterns.

Scenario 4: "I need to deserialize large JSON payloads fast" -> Use simd-json with serde compat, &'de str for zero-copy strings, and avoid #[serde(flatten)] which disables struct-level optimizations. See references/custom.md for zero-copy patterns.

Reference Files

Cross-References