Customizing Serialization

Shape JSON and config output with serde field and container attributes - no manual impls required for most cases.

Recipe

Quick-reference recipe card - copy-paste ready.

use serde::{Deserialize, Serialize};
 
#[derive(Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
struct ApiUser {
    user_id: u64,
    #[serde(skip_serializing_if = "Option::is_none")]
    nickname: Option<String>,
    #[serde(default)]
    active: bool,
}

When to reach for this: External APIs use different naming, optional fields, or nested layouts than your Rust structs.

Working Example

use serde::{Deserialize, Serialize};
 
#[derive(Serialize, Deserialize, Debug)]
#[serde(rename_all = "camelCase")]
struct User {
    user_id: u64,
    #[serde(skip_serializing_if = "Option::is_none")]
    display_name: Option<String>,
    #[serde(default)]
    role: String,
}
 
#[derive(Serialize, Deserialize, Debug)]
struct Envelope {
    #[serde(flatten)]
    user: User,
    version: u32,
}
 
fn main() {
    let u = User { user_id: 1, display_name: None, role: "member".into() };
    let json = serde_json::to_string(&u).unwrap();
    assert!(json.contains("userId"));
    assert!(!json.contains("displayName"));
 
    let env = Envelope { user: u, version: 2 };
    let flat = serde_json::to_string(&env).unwrap();
    assert!(flat.contains(r#""version":2"#));
    assert!(flat.contains(r#""userId":1"#));
}

What this demonstrates:

• rename_all maps Rust snake_case to camelCase JSON keys.
• skip_serializing_if omits None optional fields from output.
• default fills missing keys on deserialize.
• flatten merges nested struct fields into parent object.

Deep Dive

High-Value Attributes

Rust Notes

mod ts {
    use serde::{Deserializer, Serializer};
    pub fn serialize<S: Serializer>(dt: &time::OffsetDateTime, s: S) -> Result<S::Ok, S::Error> {
        s.serialize_str(&dt.format(&time::format_description::well_known::Rfc3339).unwrap())
    }
}
#[serde(with = "ts")]
created_at: time::OffsetDateTime,

Gotchas

• flatten collisions - Two flattened structs with same field names. Fix: Rename fields or nest explicitly.
• skip without default - Deserializing old data missing new fields errors. Fix: Add default or Option.
• rename_all on enums - Affects variant names too - verify OpenAPI compatibility. Fix: Snapshot tests per format.
• skip_serializing_if on empty Vec - May hide intentional empty arrays. Fix: Use skip_serializing_if = "Vec::is_empty" only when API omits empty lists.
• with module path errors - Wrong signature on custom module. Fix: Copy template from serde docs for with, serialize_with.

Alternatives

FAQs

Related

• serde Basics - Derive intro
• Enums & Tagging - Enum attributes
• Custom (De)serialization - Manual impls
• JSON with serde_json - Wire format
• serde Best Practices - Compatibility rules

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.

49454e4f4d5f434e4f5904434556494d43451b191e56181a181c1a1d