Custom Serialization: Hand-Written `Serialize` / `Deserialize`

25 min read

Most of the time #[derive(Serialize, Deserialize)] is all you need — the field names and shapes you write in Rust become the JSON you get out. But sometimes the wire format and your in-memory type are deliberately different: a color stored as three bytes but exchanged as "#1a2b3c", money kept as integer cents but sent as "49.99", or a type from a third-party crate that does not implement Serde at all. This page covers the three escape hatches for those cases: hand-writing the Serialize/Deserialize traits, retargeting a single field with serialize_with/deserialize_with, and #[serde(remote = "...")] for foreign types.

Quick Overview

What it is: Three levels of control over how a value maps to its serialized form, from “swap the codec for one field” up to “write the whole trait by hand.”
Why it matters to a TypeScript/JavaScript developer: This is the disciplined, compile-checked version of JavaScript’s toJSON() method and the JSON.parse reviver callback — the tools you reach for when the JSON shape and the object shape diverge.
The mental shift: In JavaScript, custom (de)serialization is a runtime callback that can return anything. In Rust it is a trait implementation the compiler verifies, and it stays format-agnostic — the same custom code drives JSON, YAML, MessagePack, and every other Serde format.

Note: Reach for these tools only when the derive (covered in derive-serialize.md) and the field attributes in attributes.md genuinely cannot express what you need. The #[serde(with = ...)], rename, default, and skip_serializing_if attributes solve the common cases without any hand-written code.

TypeScript/JavaScript Example

JavaScript gives you two runtime hooks for custom (de)serialization. On the way out, an object’s toJSON() method controls what JSON.stringify emits. On the way in, a reviver callback passed to JSON.parse can rebuild rich objects from primitive JSON:

1
// Custom serialization in TypeScript/JavaScript: toJSON + a reviver
2
class Color {
3
  constructor(public r: number, public g: number, public b: number) {}
4

5
  // Called automatically by JSON.stringify. We emit a hex string,
6
  // not the { r, g, b } object.
7
  toJSON(): string {
8
    const h = (n: number) => n.toString(16).padStart(2, "0");
9
    return `#${h(this.r)}${h(this.g)}${h(this.b)}`;
10
  }
11
}
12

13
const c = new Color(26, 43, 60);
14
console.log(JSON.stringify({ accent: c }));
15
// {"accent":"#1a2b3c"}
16

17
// On the way back, a reviver reconstructs the Color from the hex string.
18
const parsed = JSON.parse('{"accent":"#1a2b3c"}', (key, value) => {
19
  if (key === "accent" && typeof value === "string" && value.startsWith("#")) {
20
    const r = parseInt(value.slice(1, 3), 16);
21
    const g = parseInt(value.slice(3, 5), 16);
22
    const b = parseInt(value.slice(5, 7), 16);
23
    return new Color(r, g, b);
24
  }
25
  return value;
26
});
27

28
console.log(parsed.accent instanceof Color, parsed.accent);
29
// true Color { r: 26, g: 43, b: 60 }

This works, but notice the weaknesses Rust will close. toJSON is invoked by reflection on whatever object happens to be there — nothing checks its return type. The reviver is a stringly-typed (key, value) => any callback: you match keys by hand, the matching is easy to get subtly wrong, and a malformed "#zz" silently produces NaN channels rather than an error. There is also no symmetry — the encode logic lives in a class method and the decode logic lives in a separate callback, and nothing guarantees they agree.

Rust Equivalent

In Rust you implement the Serialize and Deserialize traits directly. The two impls sit next to each other, both are type-checked, and a bad input becomes a real, recoverable error instead of a silent NaN:

1
// Cargo.toml:
2
//   [dependencies]
3
//   serde = { version = "1", features = ["derive"] }
4
//   serde_json = "1"
5
use serde::de::{self, Deserialize, Deserializer, Visitor};
6
use serde::ser::{Serialize, Serializer};
7
use std::fmt;
8

9
struct Color {
10
    r: u8,
11
    g: u8,
12
    b: u8,
13
}
14

15
// Encode: RGB -> "#rrggbb". We talk to an abstract `Serializer`, not to JSON.
16
impl Serialize for Color {
17
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
18
    where
19
        S: Serializer,
20
    {
21
        let hex = format!("#{:02x}{:02x}{:02x}", self.r, self.g, self.b);
22
        serializer.serialize_str(&hex)
23
    }
24
}
25

26
// Decode: "#rrggbb" -> RGB, via a Visitor (Serde's pull-based callback).
27
impl<'de> Deserialize<'de> for Color {
28
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
29
    where
30
        D: Deserializer<'de>,
31
    {
32
        struct ColorVisitor;
33

34
        impl<'de> Visitor<'de> for ColorVisitor {
35
            type Value = Color;
36

37
            fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
38
                f.write_str("a hex color string like \"#1a2b3c\"")
39
            }
40

41
            fn visit_str<E>(self, value: &str) -> Result<Color, E>
42
            where
43
                E: de::Error,
44
            {
45
                let s = value
46
                    .strip_prefix('#')
47
                    .ok_or_else(|| E::custom(format!("missing leading '#' in {value:?}")))?;
48
                if s.len() != 6 {
49
                    return Err(E::custom(format!("expected 6 hex digits, got {}", s.len())));
50
                }
51
                let parse = |range: std::ops::Range<usize>| {
52
                    u8::from_str_radix(&s[range], 16)
53
                        .map_err(|e| E::custom(format!("invalid hex: {e}")))
54
                };
55
                Ok(Color {
56
                    r: parse(0..2)?,
57
                    g: parse(2..4)?,
58
                    b: parse(4..6)?,
59
                })
60
            }
61
        }
62

63
        deserializer.deserialize_str(ColorVisitor)
64
    }
65
}
66

67
fn main() {
68
    let c = Color { r: 26, g: 43, b: 60 };
69
    let json = serde_json::to_string(&c).unwrap();
70
    println!("serialized: {json}");
71

72
    let back: Color = serde_json::from_str(&json).unwrap();
73
    println!("deserialized: r={} g={} b={}", back.r, back.g, back.b);
74

75
    // Bad inputs are real errors, not silent NaN.
76
    let bad: Result<Color, _> = serde_json::from_str(r#""1a2b3c""#);
77
    println!("bad input -> {:?}", bad.err().map(|e| e.to_string()));
78

79
    let bad2: Result<Color, _> = serde_json::from_str(r##""#zzzzzz""##);
80
    println!("bad hex   -> {:?}", bad2.err().map(|e| e.to_string()));
81
}

Real output:

1
serialized: "#1a2b3c"
2
deserialized: r=26 g=43 b=60
3
bad input -> Some("missing leading '#' in \"1a2b3c\" at line 1 column 8")
4
bad hex   -> Some("invalid hex: invalid digit found in string at line 1 column 9")

The hex shape, the # prefix, and the digit-count check are all enforced on the way in — the closest JavaScript reviver would have happily returned a Color with NaN channels.

Detailed Explanation

The `Serialize` trait

Serialize has exactly one method:

1
// From the serde crate (shown for reference).
2
pub trait Serialize {
3
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
4
    where
5
        S: Serializer;
6
}

serializer is a value implementing the Serializer trait — serde_json provides one, serde_yaml another, and so on. Your job is to call methods on it describing your data: serialize_str, serialize_u64, serialize_struct, serialize_seq, and roughly two dozen more (one per type in the Serde data model). You never mention JSON; the Serializer decides what bytes those calls produce. That is why one hand-written Serialize impl works for every format — the same indirection the derive relies on (see serde-intro.md for the data-model architecture).

In the Color example, the entire encode is a single serialize_str call, because the external form is just a string. Internally Color is three u8s; externally it is one string. That asymmetry is the whole reason to hand-write it.

The `Deserialize` trait and the Visitor pattern

Deserialization is the harder direction, and the reason is structural. A Serializer is push-based: you hand it values. A Deserializer is pull-based and format-driven: it reads tokens from the input and calls you back. That callback target is the Visitor trait.

The flow in the Color example:

deserialize calls deserializer.deserialize_str(ColorVisitor). This is a hint: “I expect a string; here is who to call when you have one.”
The deserializer (for JSON) reads a string token and calls visitor.visit_str(self, "#1a2b3c").
visit_str does the parsing and either returns a Color or returns E::custom(...) for a bad input.

A Visitor can implement many visit_* methods (visit_str, visit_u64, visit_map, visit_seq, …). You only implement the ones you accept; the default for the rest is “produce a type error.” The expecting method supplies the human-readable description that appears in those error messages.

Tip: The lifetime 'de is the lifetime of the data being borrowed from the input. You almost always just write impl<'de> Deserialize<'de> and impl<'de> Visitor<'de> verbatim and move on; it only becomes interesting for zero-copy borrowing, which performance.md covers.

Why a string `Visitor` is simpler than a struct one

The Color decode only handles visit_str. When your external form is a JSON object with several keys, you instead implement visit_map, walk the keys with map.next_key() / map.next_value(), and assemble the fields yourself. Here is that fuller pattern — a Rectangle that emits a computed area field on the way out (which the derive cannot do) and ignores it on the way in:

1
// Cargo.toml:
2
//   [dependencies]
3
//   serde = { version = "1", features = ["derive"] }
4
//   serde_json = "1"
5
use serde::de::{self, Deserializer, MapAccess, Visitor};
6
use serde::ser::{Serialize, SerializeStruct, Serializer};
7
use serde::Deserialize;
8
use std::fmt;
9

10
#[derive(Debug)]
11
struct Rectangle {
12
    width: f64,
13
    height: f64,
14
}
15

16
impl Serialize for Rectangle {
17
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
18
    where
19
        S: Serializer,
20
    {
21
        // Announce a struct with THREE fields, including a computed one.
22
        let mut s = serializer.serialize_struct("Rectangle", 3)?;
23
        s.serialize_field("w", &self.width)?;
24
        s.serialize_field("h", &self.height)?;
25
        s.serialize_field("area", &(self.width * self.height))?;
26
        s.end()
27
    }
28
}
29

30
impl<'de> Deserialize<'de> for Rectangle {
31
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
32
    where
33
        D: Deserializer<'de>,
34
    {
35
        // A small derived enum gives us validated, fast key matching.
36
        #[derive(Deserialize)]
37
        #[serde(field_identifier, rename_all = "lowercase")]
38
        enum Field {
39
            W,
40
            H,
41
            Area, // accepted on input but ignored (it is computed)
42
        }
43

44
        struct RectVisitor;
45

46
        impl<'de> Visitor<'de> for RectVisitor {
47
            type Value = Rectangle;
48

49
            fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
50
                f.write_str("a rectangle object with `w` and `h`")
51
            }
52

53
            fn visit_map<M>(self, mut map: M) -> Result<Rectangle, M::Error>
54
            where
55
                M: MapAccess<'de>,
56
            {
57
                let mut width = None;
58
                let mut height = None;
59
                while let Some(key) = map.next_key()? {
60
                    match key {
61
                        Field::W => {
62
                            if width.is_some() {
63
                                return Err(de::Error::duplicate_field("w"));
64
                            }
65
                            width = Some(map.next_value()?);
66
                        }
67
                        Field::H => {
68
                            if height.is_some() {
69
                                return Err(de::Error::duplicate_field("h"));
70
                            }
71
                            height = Some(map.next_value()?);
72
                        }
73
                        Field::Area => {
74
                            let _: f64 = map.next_value()?; // read and discard
75
                        }
76
                    }
77
                }
78
                let width = width.ok_or_else(|| de::Error::missing_field("w"))?;
79
                let height = height.ok_or_else(|| de::Error::missing_field("h"))?;
80
                Ok(Rectangle { width, height })
81
            }
82
        }
83

84
        const FIELDS: &[&str] = &["w", "h", "area"];
85
        deserializer.deserialize_struct("Rectangle", FIELDS, RectVisitor)
86
    }
87
}
88

89
fn main() {
90
    let r = Rectangle { width: 3.0, height: 4.0 };
91
    let json = serde_json::to_string(&r).unwrap();
92
    println!("{json}");
93

94
    let back: Rectangle = serde_json::from_str(&json).unwrap();
95
    println!("{back:?}");
96

97
    let bad: Result<Rectangle, _> = serde_json::from_str(r#"{"w":3.0}"#);
98
    println!("{:?}", bad.err().map(|e| e.to_string()));
99
}

Real output:

1
{"w":3.0,"h":4.0,"area":12.0}
2
Rectangle { width: 3.0, height: 4.0 }
3
Some("missing field `h` at line 1 column 9")

This is exactly what #[derive(Deserialize)] generates internally — the derive writes this visitor for you. Seeing it once explains why deserialization “just works” with fields in any order and reports precise missing-field errors: there is a state machine doing it.

`serialize_with` / `deserialize_with`: customize one field, keep the derive

Hand-writing the full traits for a whole struct just to special-case one field is overkill. The serialize_with and deserialize_with attributes let you keep #[derive(Serialize, Deserialize)] on the struct and point a single field at standalone functions. Those functions have the same signatures as the trait methods, but they are free functions, not impls:

1
// Cargo.toml:
2
//   [dependencies]
3
//   serde = { version = "1", features = ["derive"] }
4
//   serde_json = "1"
5
use serde::{Deserialize, Deserializer, Serialize, Serializer};
6

7
// Stored as seconds; exchanged as milliseconds.
8
fn serialize_epoch_millis<S>(secs: &u64, serializer: S) -> Result<S::Ok, S::Error>
9
where
10
    S: Serializer,
11
{
12
    serializer.serialize_u64(secs * 1000)
13
}
14

15
fn deserialize_epoch_millis<'de, D>(deserializer: D) -> Result<u64, D::Error>
16
where
17
    D: Deserializer<'de>,
18
{
19
    let millis = u64::deserialize(deserializer)?;
20
    Ok(millis / 1000)
21
}
22

23
// Stored as Vec<String>; exchanged as one comma-separated string.
24
fn serialize_csv<S>(tags: &[String], serializer: S) -> Result<S::Ok, S::Error>
25
where
26
    S: Serializer,
27
{
28
    serializer.serialize_str(&tags.join(","))
29
}
30

31
fn deserialize_csv<'de, D>(deserializer: D) -> Result<Vec<String>, D::Error>
32
where
33
    D: Deserializer<'de>,
34
{
35
    let s = String::deserialize(deserializer)?;
36
    if s.is_empty() {
37
        return Ok(Vec::new());
38
    }
39
    Ok(s.split(',').map(|t| t.trim().to_string()).collect())
40
}
41

42
#[derive(Debug, Serialize, Deserialize)]
43
struct Event {
44
    name: String,
45
    #[serde(
46
        serialize_with = "serialize_epoch_millis",
47
        deserialize_with = "deserialize_epoch_millis"
48
    )]
49
    timestamp_secs: u64,
50
    #[serde(serialize_with = "serialize_csv", deserialize_with = "deserialize_csv")]
51
    tags: Vec<String>,
52
}
53

54
fn main() {
55
    let ev = Event {
56
        name: "login".into(),
57
        timestamp_secs: 1_700_000_000,
58
        tags: vec!["auth".into(), "web".into()],
59
    };
60

61
    let json = serde_json::to_string_pretty(&ev).unwrap();
62
    println!("{json}");
63

64
    let wire = r#"{"name":"logout","timestamp_secs":1700000123000,"tags":"auth,mobile"}"#;
65
    let back: Event = serde_json::from_str(wire).unwrap();
66
    println!("{back:?}");
67
}

Real output:

1
{
2
  "name": "login",
3
  "timestamp_secs": 1700000000000,
4
  "tags": "auth,web"
5
}
6
Event { name: "logout", timestamp_secs: 1700000123, tags: ["auth", "mobile"] }

A few mechanics worth internalizing:

The serialize_with function takes &T (a reference to the field), the deserialize_with function returns Result<T, _> (the field’s type). The compiler enforces both.
The argument is a string path to a function, e.g. "serialize_epoch_millis" or "crate::codecs::serialize_csv". It is resolved at macro-expansion time, so a typo is a real “cannot find function” error, not a runtime miss.
If you have both directions and they belong together, group them in a module with serialize/deserialize functions and use the single #[serde(with = "module_path")] attribute instead. That is the form the Real-World Example below uses, and the same form documented in attributes.md.

`#[serde(remote = "...")]`: serializing a foreign type

The hardest case is a type you do not own and cannot annotate — Rust’s orphan rule (see section 09) forbids implementing Serialize for a type from another crate. Serde’s answer is remote derive: you declare a local mirror struct with identical fields, tie it to the foreign type with #[serde(remote = "...")], and Serde generates the impls — but emits them as associated functions on your mirror, which you then attach to fields with #[serde(with = "...")]:

1
// Cargo.toml:
2
//   [dependencies]
3
//   serde = { version = "1", features = ["derive"] }
4
//   serde_json = "1"
5
use serde::{Deserialize, Serialize};
6

7
// Pretend this comes from a third-party crate we cannot edit; it has NO
8
// Serde derives. (In real code this would be `other_crate::Duration`.)
9
mod other_crate {
10
    #[derive(Debug)]
11
    pub struct Duration {
12
        pub secs: u64,
13
        pub nanos: u32,
14
    }
15

16
    impl Duration {
17
        pub fn new(secs: u64, nanos: u32) -> Self {
18
            Duration { secs, nanos }
19
        }
20
    }
21
}
22

23
use other_crate::Duration;
24

25
// A local mirror with the SAME fields, tied to the remote type.
26
// Serde generates Serialize/Deserialize *for Duration* from this definition.
27
#[derive(Serialize, Deserialize)]
28
#[serde(remote = "Duration")]
29
struct DurationDef {
30
    secs: u64,
31
    nanos: u32,
32
}
33

34
#[derive(Serialize, Deserialize, Debug)]
35
struct Timer {
36
    label: String,
37
    // Route this field through the generated remote impl.
38
    #[serde(with = "DurationDef")]
39
    interval: Duration,
40
}
41

42
fn main() {
43
    let timer = Timer {
44
        label: "heartbeat".into(),
45
        interval: Duration::new(30, 500_000),
46
    };
47

48
    let json = serde_json::to_string(&timer).unwrap();
49
    println!("{json}");
50

51
    let back: Timer = serde_json::from_str(&json).unwrap();
52
    println!("{back:?}");
53
}

Real output:

1
{"label":"heartbeat","interval":{"secs":30,"nanos":500000}}
2
Timer { label: "heartbeat", interval: Duration { secs: 30, nanos: 500000 } }

The mirror’s fields must match the remote type’s fields (name and type) so the generated code can construct it. If the remote type has private fields, you supply a #[serde(getter = "...")] for serialization and the remote type must expose a constructor or From for deserialization. This is the mechanism crates like chrono use under the hood — though in practice you should prefer a crate’s own serde feature (e.g. chrono = { version = "0.4", features = ["serde"] }) over rolling your own mirror; see other-formats.md and the ecosystem note in Best Practices.

Key Differences

Aspect	TypeScript / JavaScript	Rust + Serde
Encode hook	`toJSON()` method, invoked by reflection	`Serialize` trait impl, resolved at compile time
Decode hook	`JSON.parse` reviver, a `(key, value) => any` callback	`Deserialize` trait + a `Visitor` state machine
Type checking	None — `toJSON` may return anything	Return types enforced by the compiler
Bad input	Often silent (`NaN`, `undefined`)	A real `Result::Err` with a precise message
Format coupling	Tied to JSON specifically	Format-agnostic; same impl drives every format
One-field tweak	Re-implement `toJSON` for the whole object	`#[serde(serialize_with/deserialize_with/with)]` on one field
Foreign types	Patch the prototype, or wrap	`#[serde(remote = "...")]` mirror struct
Encode/decode symmetry	Two unrelated places (method vs. callback)	Two traits, conventionally written side by side

Why Rust splits it into traits and a Visitor

JavaScript can afford a single (key, value) => any reviver because everything is dynamically typed and the JSON parser already produced generic objects. Rust has no runtime reflection and monomorphizes generics away, so the parser cannot “just build an object” — it does not know the target shape. The Visitor is how the type tells the format what tokens it can accept, decoupling the two so that any Deserializer (JSON, YAML, binary) can drive any Deserialize type. It is more ceremony than a reviver, but it is the ceremony that makes the result fast and type-safe.

Common Pitfalls

Pitfall 1: Using a remote type on a field without `#[serde(with = ...)]`

Declaring the #[serde(remote = "...")] mirror is only half the job — it generates functions, it does not implement the trait for the remote type. You must still route each field through it. Forgetting that yields the standard “trait not implemented” error:

1
use serde::{Deserialize, Serialize};
2

3
mod other_crate {
4
    #[derive(Debug)]
5
    pub struct Duration {
6
        pub secs: u64,
7
        pub nanos: u32,
8
    }
9
}
10
use other_crate::Duration;
11

12
#[derive(Serialize, Deserialize)]
13
#[serde(remote = "Duration")]
14
struct DurationDef {
15
    secs: u64,
16
    nanos: u32,
17
}
18

19
#[derive(Serialize, Deserialize, Debug)] // does not compile (error0277)
20
struct Timer {
21
    label: String,
22
    interval: Duration, // forgot #[serde(with = "DurationDef")]
23
}
24

25
fn main() {
26
    let _ = Timer { label: "x".into(), interval: Duration { secs: 1, nanos: 0 } };
27
}

The real compiler error (cargo build):

1
error[E0277]: the trait bound `other_crate::Duration: serde::Serialize` is not satisfied
2
    --> src/main.rs:19:10
3
     |
4
  19 | #[derive(Serialize, Deserialize, Debug)]
5
     |          ^^^^^^^^^ the trait `Serialize` is not implemented for `other_crate::Duration`
6
...
7
  22 |     interval: Duration, // forgot #[serde(with = "DurationDef")]
8
     |     -------- required by a bound introduced by this call
9
     |
10
     = note: for local types consider adding `#[derive(serde::Serialize)]` to your `other_crate::Duration` type
11
     = note: for types from other crates check whether the crate offers a `serde` feature flag

Fix: add #[serde(with = "DurationDef")] to the interval field. The compiler note’s second line is also the better long-term advice: check whether the crate has a serde feature before writing a mirror at all.

Pitfall 2: A `serialize_with` / `deserialize_with` function with the wrong signature

The attribute points at a string path, so a wrong signature is not caught until the macro-generated call site tries to use it. The two signatures are easy to confuse — serialize_with takes &T, deserialize_with returns Result<T, _>. Passing the field by value to serialize_with, returning the wrong type, or mixing up Serializer/Deserializer all produce mismatch errors at compile time. Copy a known-good pair (like the ones above) and edit the body — do not hand-type the generic bounds from memory.

Warning: The function path is a string, so a misspelled name like "serialize_epoc_millis" produces a “cannot find function” error pointing at the #[derive] line, not the field — read past the derive to find the real cause.

Pitfall 3: Mismatched field count in `serialize_struct`

serializer.serialize_struct("Name", N)? declares that exactly N fields follow. The count is an optimization hint that some formats (notably binary ones and serde_json’s map machinery) rely on. If you pass 2 but call serialize_field three times — or vice versa — formats that pre-allocate by the count can misbehave or panic. Always make the number match the number of serialize_field calls. The same applies to serialize_seq(Some(len)) and serialize_map(Some(len)); pass None if you genuinely do not know the length up front.

Pitfall 4: Forgetting `visit_str` (or implementing the wrong `visit_*`)

A Visitor only handles the visit_* methods you implement; every other input type falls through to a default that returns a type error. If your deserialize method hints deserialize_str but you implemented visit_string instead of visit_str (or omitted it entirely), valid input is rejected with an “invalid type” error. Match the visit_* method to the token the deserializer will actually produce: JSON strings arrive at visit_str, JSON numbers at visit_u64/visit_i64/visit_f64, JSON objects at visit_map, arrays at visit_seq.

Pitfall 5: Trying to implement Serde traits on a foreign type directly

The instinct from other languages is to write impl Serialize for chrono::DateTime<Utc>. Rust’s orphan rule rejects this: you may implement a trait for a type only if you own the trait or the type. The error is E0117 (“only traits defined in the current crate can be implemented for types defined outside of the crate”). Remote derive exists precisely to work around this without violating the rule — the impl is generated for your mirror, and the with attribute wires it in. See section 09’s orphan rule page for the underlying reasoning.

Best Practices

Prefer attributes over hand-written traits. #[serde(with = ...)], rename, default, and skip_serializing_if (in attributes.md) cover most divergence between wire and memory. Hand-write the full trait only when no attribute fits.
Prefer a crate’s serde feature over remote derive. Before mirroring a foreign type, check for a feature flag: uuid = { version = "1", features = ["serde"] }, chrono = { version = "0.4", features = ["serde"] }, rust_decimal = { version = "1", features = ["serde"] }. Remote derive is the fallback for crates that offer none.
Group a with pair into a module. When a field needs both custom directions, put serialize and deserialize functions in a module and use #[serde(with = "module")] once, rather than two separate attributes. It keeps the encode/decode logic provably adjacent.
Always return E::custom(...) for bad input, never panic! or unwrap. Deserialization is a fallible boundary; a hand-written Deserialize that panics turns malformed input into a crash. Return a descriptive error so the caller can handle it.
Write a round-trip test. The single most valuable test for custom (de)serialization is assert_eq!(value, from_str(&to_string(&value))). It catches encode/decode drift immediately. See section 13.
Keep serialize_with/deserialize_with functions pure and small. They run inside the serializer; doing I/O or allocating heavily there is a smell. Transform data only.
Make expecting describe the accepted form, not the type name. “a hex color string like #1a2b3c” produces far better error messages than “a Color”.

Real-World Example

A payment record exchanged with an external API. Three divergences from a naive derive: money is stored as integer cents (never floats — JavaScript’s IEEE-754 number famously loses precision on money) but exchanged as a "49.99" decimal string; the upstream service sends statuses in SCREAMING_SNAKE_CASE; and the money codec lives in a reusable module wired in with a single #[serde(with = "money")].

1
// Cargo.toml:
2
//   [dependencies]
3
//   serde = { version = "1", features = ["derive"] }
4
//   serde_json = "1"
5
use serde::de::Error as DeError;
6
use serde::{Deserialize, Deserializer, Serialize, Serializer};
7

8
// A reusable codec module: cents <-> "NN.cc" decimal string.
9
mod money {
10
    use super::*;
11

12
    pub fn serialize<S>(cents: &i64, serializer: S) -> Result<S::Ok, S::Error>
13
    where
14
        S: Serializer,
15
    {
16
        let sign = if *cents < 0 { "-" } else { "" };
17
        let abs = cents.unsigned_abs();
18
        let formatted = format!("{sign}{}.{:02}", abs / 100, abs % 100);
19
        serializer.serialize_str(&formatted)
20
    }
21

22
    pub fn deserialize<'de, D>(deserializer: D) -> Result<i64, D::Error>
23
    where
24
        D: Deserializer<'de>,
25
    {
26
        let s = String::deserialize(deserializer)?;
27
        let (sign, digits) = match s.strip_prefix('-') {
28
            Some(rest) => (-1, rest),
29
            None => (1, s.as_str()),
30
        };
31
        let (whole, frac) = digits.split_once('.').unwrap_or((digits, "0"));
32
        let whole: i64 = whole.parse().map_err(D::Error::custom)?;
33
        let frac_padded = format!("{frac:0<2}");
34
        let cents: i64 = frac_padded[..2].parse().map_err(D::Error::custom)?;
35
        Ok(sign * (whole * 100 + cents))
36
    }
37
}
38

39
#[derive(Debug, Serialize, Deserialize)]
40
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
41
enum PaymentStatus {
42
    Pending,
43
    Settled,
44
    Refunded,
45
}
46

47
#[derive(Debug, Serialize, Deserialize)]
48
struct Payment {
49
    id: String,
50
    #[serde(with = "money")]
51
    amount_cents: i64,
52
    currency: String,
53
    status: PaymentStatus,
54
}
55

56
fn main() {
57
    let payment = Payment {
58
        id: "pay_88".into(),
59
        amount_cents: 4999,
60
        currency: "USD".into(),
61
        status: PaymentStatus::Settled,
62
    };
63

64
    let json = serde_json::to_string_pretty(&payment).unwrap();
65
    println!("{json}");
66

67
    // Parse an inbound payload from the upstream service.
68
    let wire = r#"{"id":"pay_99","amount_cents":"12.05","currency":"EUR","status":"REFUNDED"}"#;
69
    let parsed: Payment = serde_json::from_str(wire).unwrap();
70
    println!("{parsed:?}");
71
    println!("stored cents = {}", parsed.amount_cents);
72
}

Real output:

1
{
2
  "id": "pay_88",
3
  "amount_cents": "49.99",
4
  "currency": "USD",
5
  "status": "SETTLED"
6
}
7
Payment { id: "pay_99", amount_cents: 1205, currency: "EUR", status: Refunded }
8
stored cents = 1205

Internally amount_cents is always an exact integer — arithmetic on it cannot lose a penny — while the wire stays in the decimal string the external API expects. The money module is reusable across every type that carries money, and the #[serde(rename_all = "SCREAMING_SNAKE_CASE")] attribute handles the status casing without any custom code. This Payment is the kind of type a web handler would accept and return; see how typed payloads flow through HTTP in section 16.

Exercises

Exercise 1: A custom `Serialize` for a newtype

Difficulty: Easy

Objective: Hand-write the Serialize trait for a type whose external form differs from its internal one.

Instructions:

Define a tuple struct Percentage(u8).
Implement Serialize so a Percentage(75) serializes to the JSON string "75%" (with a literal percent sign), not the number 75.
In main, serialize Percentage(75) and print the result.

1
use serde::ser::{Serialize, Serializer};
2

3
struct Percentage(u8);
4

5
impl Serialize for Percentage {
6
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
7
    where
8
        S: Serializer,
9
    {
10
        // TODO: serialize as the string "75%"
11
        todo!()
12
    }
13
}
14

15
fn main() {
16
    // TODO: serialize Percentage(75) and print it
17
}

Solution

1
use serde::ser::{Serialize, Serializer};
2

3
struct Percentage(u8);
4

5
impl Serialize for Percentage {
6
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
7
    where
8
        S: Serializer,
9
    {
10
        serializer.serialize_str(&format!("{}%", self.0))
11
    }
12
}
13

14
fn main() {
15
    let p = Percentage(75);
16
    println!("{}", serde_json::to_string(&p).unwrap());
17
    // "75%"
18
}

Real output:

1
"75%"

Exercise 2: A lenient `deserialize_with`

Difficulty: Medium

Objective: Use deserialize_with to accept input in more than one shape — the kind of leniency real-world APIs demand.

Instructions:

Write a free function flexible_bool suitable for #[serde(deserialize_with = "...")] that accepts either a real JSON boolean or a string. The strings "yes", "true", "1" mean true; "no", "false", "0" mean false (case-insensitive). Anything else is an error.
Put it on a Settings { dark_mode: bool } struct.
In main, deserialize {"dark_mode":true}, {"dark_mode":"yes"}, and {"dark_mode":"NO"}, then show that {"dark_mode":"maybe"} produces an error.

Tip: A small #[serde(untagged)] enum is the cleanest way to accept “a bool or a string.”

Solution

1
use serde::de::Error;
2
use serde::{Deserialize, Deserializer};
3

4
fn flexible_bool<'de, D>(deserializer: D) -> Result<bool, D::Error>
5
where
6
    D: Deserializer<'de>,
7
{
8
    #[derive(Deserialize)]
9
    #[serde(untagged)]
10
    enum BoolOrString {
11
        Bool(bool),
12
        Str(String),
13
    }
14

15
    match BoolOrString::deserialize(deserializer)? {
16
        BoolOrString::Bool(b) => Ok(b),
17
        BoolOrString::Str(s) => match s.to_lowercase().as_str() {
18
            "yes" | "true" | "1" => Ok(true),
19
            "no" | "false" | "0" => Ok(false),
20
            other => Err(D::Error::custom(format!("not a boolean: {other:?}"))),
21
        },
22
    }
23
}
24

25
#[derive(Debug, Deserialize)]
26
struct Settings {
27
    #[serde(deserialize_with = "flexible_bool")]
28
    dark_mode: bool,
29
}
30

31
fn main() {
32
    for input in [
33
        r#"{"dark_mode":true}"#,
34
        r#"{"dark_mode":"yes"}"#,
35
        r#"{"dark_mode":"NO"}"#,
36
    ] {
37
        let s: Settings = serde_json::from_str(input).unwrap();
38
        println!("{input} -> {s:?}");
39
    }
40
    let bad: Result<Settings, _> = serde_json::from_str(r#"{"dark_mode":"maybe"}"#);
41
    println!("{:?}", bad.err().map(|e| e.to_string()));
42
}

Real output:

1
{"dark_mode":true} -> Settings { dark_mode: true }
2
{"dark_mode":"yes"} -> Settings { dark_mode: true }
3
{"dark_mode":"NO"} -> Settings { dark_mode: false }
4
Some("not a boolean: \"maybe\" at line 1 column 21")

Exercise 3: A full round-tripping `Serialize` + `Deserialize`

Difficulty: Hard

Objective: Implement both traits by hand for a type that serializes as a single string and validates strictly on the way back.

Instructions:

Define struct Version { major: u16, minor: u16, patch: u16 } deriving Debug and PartialEq.
Implement Serialize so it produces the string "MAJOR.MINOR.PATCH" (e.g. "1.4.2").
Implement Deserialize with a Visitor whose visit_str parses exactly three dot-separated u16s. Reject too-few components, non-numeric components, and too-many components, each with a descriptive E::custom error.
In main, round-trip a Version, assert_eq! it survives, and show that "1.x" fails with a useful message.

Solution

1
use serde::de::{self, Deserialize, Deserializer, Visitor};
2
use serde::ser::{Serialize, Serializer};
3
use std::fmt;
4

5
#[derive(Debug, PartialEq)]
6
struct Version {
7
    major: u16,
8
    minor: u16,
9
    patch: u16,
10
}
11

12
impl Serialize for Version {
13
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
14
    where
15
        S: Serializer,
16
    {
17
        serializer.serialize_str(&format!("{}.{}.{}", self.major, self.minor, self.patch))
18
    }
19
}
20

21
impl<'de> Deserialize<'de> for Version {
22
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
23
    where
24
        D: Deserializer<'de>,
25
    {
26
        struct VersionVisitor;
27

28
        impl<'de> Visitor<'de> for VersionVisitor {
29
            type Value = Version;
30

31
            fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
32
                f.write_str(r#"a version string like "1.4.2""#)
33
            }
34

35
            fn visit_str<E>(self, v: &str) -> Result<Version, E>
36
            where
37
                E: de::Error,
38
            {
39
                let mut parts = v.split('.');
40
                let mut next = |name: &str| -> Result<u16, E> {
41
                    parts
42
                        .next()
43
                        .ok_or_else(|| E::custom(format!("missing {name}")))?
44
                        .parse()
45
                        .map_err(|e| E::custom(format!("bad {name}: {e}")))
46
                };
47
                let major = next("major")?;
48
                let minor = next("minor")?;
49
                let patch = next("patch")?;
50
                if parts.next().is_some() {
51
                    return Err(E::custom("too many version components"));
52
                }
53
                Ok(Version { major, minor, patch })
54
            }
55
        }
56

57
        deserializer.deserialize_str(VersionVisitor)
58
    }
59
}
60

61
fn main() {
62
    let v = Version { major: 1, minor: 4, patch: 2 };
63
    let json = serde_json::to_string(&v).unwrap();
64
    println!("{json}");
65

66
    let back: Version = serde_json::from_str(&json).unwrap();
67
    println!("{back:?}");
68
    assert_eq!(v, back);
69

70
    let bad: Result<Version, _> = serde_json::from_str(r#""1.x""#);
71
    println!("{:?}", bad.err().map(|e| e.to_string()));
72
}

Real output:

1
"1.4.2"
2
Version { major: 1, minor: 4, patch: 2 }
3
Some("bad minor: invalid digit found in string at line 1 column 5")

Custom Serialization: Hand-Written Serialize / Deserialize

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

The Serialize trait

The Deserialize trait and the Visitor pattern

Why a string Visitor is simpler than a struct one

serialize_with / deserialize_with: customize one field, keep the derive

#[serde(remote = "...")]: serializing a foreign type

Key Differences

Why Rust splits it into traits and a Visitor

Common Pitfalls

Pitfall 1: Using a remote type on a field without #[serde(with = ...)]

Pitfall 2: A serialize_with / deserialize_with function with the wrong signature

Pitfall 3: Mismatched field count in serialize_struct

Pitfall 4: Forgetting visit_str (or implementing the wrong visit_*)

Pitfall 5: Trying to implement Serde traits on a foreign type directly

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: A custom Serialize for a newtype

Exercise 2: A lenient deserialize_with

Exercise 3: A full round-tripping Serialize + Deserialize

Custom Serialization: Hand-Written `Serialize` / `Deserialize`

The `Serialize` trait

The `Deserialize` trait and the Visitor pattern

Why a string `Visitor` is simpler than a struct one

`serialize_with` / `deserialize_with`: customize one field, keep the derive

`#[serde(remote = "...")]`: serializing a foreign type

Pitfall 1: Using a remote type on a field without `#[serde(with = ...)]`

Pitfall 2: A `serialize_with` / `deserialize_with` function with the wrong signature

Pitfall 3: Mismatched field count in `serialize_struct`

Pitfall 4: Forgetting `visit_str` (or implementing the wrong `visit_*`)

Exercise 1: A custom `Serialize` for a newtype

Exercise 2: A lenient `deserialize_with`

Exercise 3: A full round-tripping `Serialize` + `Deserialize`