existential-birds/beagle / plugins/beagle-rust/skills/serde-code-review
serde-code-review
VerifiedReviews serde serialization code for derive patterns, enum representations, custom implementations, and common serialization bugs. Use when reviewing Rust code that uses serde, serde_json, toml, or any serde-based serialization format. Covers attribute macros, field renaming, and format-specific pitfalls.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.1 KB |
| references/custom-serialization.md | markdown | 6.4 KB |
| references/derive-patterns.md | markdown | 5.7 KB |
references/derive-patterns.md
View on GitHub# Derive Patterns
## Enum Tagging Strategies
Serde supports four enum representations. The choice affects wire format, readability, and compatibility.
### Externally Tagged (Default)
```rust
#[derive(Serialize, Deserialize)]
enum Message {
Text(String),
Image { url: String, alt: String },
}
// JSON: {"Text": "hello"} or {"Image": {"url": "...", "alt": "..."}}
```
Simple but produces awkward JSON for variants with data.
### Internally Tagged
```rust
#[derive(Serialize, Deserialize)]
#[serde(tag = "type")]
enum Message {
Text { content: String },
Image { url: String, alt: String },
}
// JSON: {"type": "Text", "content": "hello"}
```
Clean and common for API types. Requires all variants to be struct-like (no tuple variants). The tag field name must not collide with variant field names.
### Adjacently Tagged
```rust
#[derive(Serialize, Deserialize)]
#[serde(tag = "type", content = "data")]
enum Message {
Text(String),
Image { url: String, alt: String },
}
// JSON: {"type": "Text", "data": "hello"}
```
Supports both tuple and struct variants. Good for message protocols where type and payload are separate.
### Untagged
```rust
#[derive(Serialize, Deserialize)]
#[serde(untagged)]
enum ApiResponse {
Success { data: Value },
Error { error: String, code: u32 },
}
// JSON: {"data": {...}} or {"error": "...", "code": 404}
```
Discriminated by structure, not a tag. Serde tries each variant in order until one succeeds. Watch for ambiguity — if two variants could match the same input, serde uses the first match.
## Field Attributes
### rename_all
Converts Rust's `snake_case` to the wire format's convention.
```rust
#[derive(Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
struct ApiResponse {
user_name: String, // → "userName"
created_at: DateTime, // → "createdAt"
}
#[derive(Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
enum Status {
InProgress, // → "in_progress"
Complete, // → "complete"
}
```
Common values: `camelCase`, `snake_case`, `SCREAMING_SNAKE_CASE`, `kebab-case`, `lowercase`, `UPPERCASE`.
### skip_serializing_if
Omits fields from output when a condition is true. Essential for clean API responses.
```rust
#[derive(Serialize)]
struct User {
name: String,
#[serde(skip_serializing_if = "Option::is_none")]
email: Option<String>,
#[serde(skip_serializing_if = "Vec::is_empty")]
tags: Vec<String>,
}
// With email=None, tags=[]: {"name": "Alice"}
// Without skip: {"name": "Alice", "email": null, "tags": []}
```
### default
Provides fallback values during deserialization when a field is missing.
```rust
#[derive(Deserialize)]
struct Config {
host: String,
#[serde(default = "default_port")]
port: u16,
#[serde(default)] // uses Default::default()
debug: bool,
}
fn default_port() -> u16 { 8080 }
```
### flatten
Inlines a struct's fields into the parent. Useful for composition but can cause subtle issues.
```rust
#[derive(Serialize, Deserialize)]
struct Request {
id: Uuid,
#[serde(flatten)]
metadata: Metadata, // metadata fields appear at top level
}
#[derive(Serialize, Deserialize)]
struct Metadata {
timestamp: DateTime<Utc>,
source: String,
}
// JSON: {"id": "...", "timestamp": "...", "source": "..."}
```
**Pitfall:** If `Request` and `Metadata` have a field with the same name, one silently wins. Use `#[serde(flatten)]` only when field names are guaranteed not to collide.
## Edition 2024: Reserved `gen` Keyword
In Rust edition 2024, `gen` is a reserved keyword. Any serde field or enum variant named `gen` will fail to compile. Use `r#gen` as the Rust identifier and `#[serde(rename)]` to preserve the wire format name.
```rust
// BAD — fails to compile on edition 2024
#[derive(Serialize, Deserialize)]
struct Model {
gen: u32,
}
// GOOD — compiles on edition 2024, wire format unchanged
#[derive(Serialize, Deserialize)]
struct Model {
#[serde(rename = "gen")]
r#gen: u32,
}
// GOOD — enum variant
#[derive(Serialize, Deserialize)]
enum Phase {
#[serde(rename = "gen")]
Generation,
Evaluation,
}
```
This also applies to `#[serde(alias = "gen")]` — the alias string is fine, but the Rust identifier must use `r#gen`.
## Edition 2024: `#[expect]` for Serde-Only Fields
Fields that exist solely for deserialization (e.g., skipped during serialization) may trigger unused warnings. Prefer `#[expect(dead_code)]` over `#[allow(dead_code)]` — it warns you when the suppression becomes unnecessary.
```rust
// BAD — allow stays forever even if the field becomes used
#[allow(dead_code)]
#[serde(skip_serializing)]
legacy_id: Option<String>,
// GOOD — expect warns when suppression is no longer needed
#[expect(dead_code)]
#[serde(skip_serializing)]
legacy_id: Option<String>,
```
## Database Type Alignment
When types are used with both serde and sqlx, keep representations consistent:
```rust
#[derive(Debug, Clone, Serialize, Deserialize, sqlx::Type)]
#[serde(rename_all = "snake_case")]
#[sqlx(type_name = "varchar", rename_all = "snake_case")]
pub enum Status {
Pending,
InProgress,
Complete,
}
```
Both serde and sqlx will use `"pending"`, `"in_progress"`, `"complete"`. Mismatched casing between the two causes bugs that are hard to trace.
## Review Questions
1. Is the enum tagging strategy explicit and appropriate for the wire format?
2. Is `rename_all` consistent across related types?
3. Are optional fields using `skip_serializing_if` for clean output?
4. Does `#[serde(flatten)]` risk field name collisions?
5. Do serde and sqlx enum representations match?
6. Are any fields or variants named `gen` (edition 2024 reserved keyword)?
7. Are lint suppressions on serde-only fields using `#[expect]` instead of `#[allow]`?
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |