serde Best Practices

Rules for stable, versioned, forward-compatible serialization schemas in production Rust services.

How to Use This List

• Apply when designing public APIs, event buses, and persisted blobs.
• Add snapshot tests in CI for every schema change.
• Treat breaking wire changes like database migrations.

A - Schema Design

• Prefer explicit enum tags in public JSON. Avoid untagged for external APIs.
• Use #[serde(default)] on new optional fields. Old clients can omit them.
• Add version field to persisted blobs. Migrate readers explicitly.
• Separate API DTOs from domain models when shapes diverge. Do not leak internal names.
• Document null vs missing semantics. Option skips vs explicit null affects clients.

B - Compatibility

• Never remove or rename fields without a version bump. Use alias for renames during transition.
• deny_unknown_fields on inbound untrusted data. Reject surprise keys.
• Snapshot JSON for every enum variant. Catch tagging regressions in CI.
• Test round-trip per wire format you ship. JSON != bincode layout.
• Keep #[serde(other)] variant for unknown event types. Forward-compatible consumers.

C - Performance & Safety

• Cap request body size before deserialize. Tower body limit or manual check.
• Use borrowed &str only when buffer outlives value. Default to String in handlers.
• Avoid serde_json::Value for hot paths. Typed structs or streaming.
• Limit collection sizes in custom deserializers. Prevent allocation bombs.
• Do not unwrap parse results on untrusted input. Map to typed errors.

D - Operations

• Log serde failures without full payload. Hash or truncate for GDPR.
• Pin serde and format crates in workspace. Reproducible builds.
• Feature-gate optional formats. Smaller binaries when only JSON needed.
• Align OpenAPI/Protobuf with serde types. Single source of truth where possible.
• Run cargo fuzz on decode entry points. Find panics before attackers do.

FAQs

Related

• serde Basics - Fundamentals
• Enums & Tagging - Wire shapes
• Error Handling & Validation - Untrusted input
• API Design Basics - HTTP contracts
• Web Backends Best Practices - Service layer

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+.