skip to content

A Rust struct with a `Cow<'a, str>` field is deserialized with serde_json; why is the field always `Cow::Owned`, and when can it borrow instead?

level: seniorimportance: nice to knowfreq 25%

answer

  1. serde's impl for Cow
  2. opt in per field
  3. escapes force a new buffer
  4. readers cannot lend bytes

basics

~10 s

serde's Deserialize impl for Cow<'a, T> always deserializes T::Owned and wraps it in Cow::Owned. With #[serde(borrow)] on the field, serde_json::from_str yields Cow::Borrowed for strings without escapes and Cow::Owned when it must unescape.

solid answer

~40 s

serde implements `Deserialize<'de> for Cow<'a, T>` where `T: ?Sized + ToOwned, T::Owned: Deserialize<'de>`, and its body is `T::Owned::deserialize(deserializer).map(Cow::Owned)`: without help, a `Cow<'a, str>` field always allocates a `String`. Adding `#[serde(borrow)]` to the field makes the derive call a borrowing helper instead and adds a `'de: 'a` bound, so the field may point into the input. serde_json's `from_str` then lends a slice of the input for a string with no escape sequences, giving `Cow::Borrowed`, but a string such as `"line\nbreak"` must be decoded into a new buffer, giving `Cow::Owned`. That fallback is why `Cow` beats `&'a str` for borrowed fields: a `&str` field fails on escaped input with "expected a borrowed string". The price is that a borrowing struct is not `DeserializeOwned`, so `serde_json::from_reader` will not accept it.

code

rust · 23 lines
rust
use serde::Deserialize;
use std::borrow::Cow;

#[derive(Deserialize)]
struct Event<'a> {
    plain: Cow<'a, str>,
    #[serde(borrow)]
    zero_copy: Cow<'a, str>,
}

fn kind(c: &Cow<'_, str>) -> &'static str {
    if matches!(c, Cow::Borrowed(_)) { "Borrowed" } else { "Owned" }
}

fn main() {
    let json = r#"{"plain":"abc","zero_copy":"abc"}"#;
    let e: Event = serde_json::from_str(json).unwrap();
    println!("plain={} zero_copy={}", kind(&e.plain), kind(&e.zero_copy));

    let escaped = r#"{"plain":"a","zero_copy":"line\nbreak"}"#;
    let e: Event = serde_json::from_str(escaped).unwrap();
    println!("escaped zero_copy={}", kind(&e.zero_copy));
}

go deeper

for a junior

Recall that a Cow<str> field can hold either borrowed or owned text, and that serde fills it with an owned String unless told otherwise.

for a middle

Explain serde's Deserialize impl for Cow, what #[serde(borrow)] changes in the derive, and why an escaped JSON string still produces Cow::Owned.

for a senior

Choose field types for a parser on a hot path: Cow with borrow for in-memory input, owned types for readers, and into_owned to detach to 'static when caching.

for a principal

Decide where zero-copy deserialization is worth a lifetime parameter on public types, and keep owned DTOs at the boundaries where data is stored or shared.

## serde's default for `Cow` serde ships a `Deserialize` impl for `std::borrow::Cow` (in serde 1.0.229 it lives in `serde_core`): ```rust impl<'de, 'a, T> Deserialize<'de> for Cow<'a, T> where T: ?Sized + ToOwned, T::Owned: Deserialize<'de>, { fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> { T::Owned::deserialize(d).map(Cow::Owned) } } ``` For a `Cow<'a, str>` field that means: **deserialize a `String`, wrap it in `Cow::Owned`**. The lifetime `'a` is unconnected to the input lifetime `'de`, so serde could not hand out a borrow even if it wanted to. A struct whose fields are all plain `Cow<'a, str>` therefore allocates exactly as if they were `String`. ## Opting in with `#[serde(borrow)]` The derive treats `&'a str` and `&'a [u8]` fields as borrowed automatically, but **not** `Cow` fields. You opt in per field: ```rust #[derive(Deserialize)] struct Event<'a> { #[serde(borrow)] name: Cow<'a, str>, } ``` With the attribute, the generated code: 1. adds the bound `'de: 'a`, so the input must outlive the struct; 2. deserializes the field through serde's string visitor for `Cow`, which returns `Cow::Borrowed` when the format offers a borrowed `&'de str` and `Cow::Owned` when it offers a temporary or owned string. ## When the field still ends up `Owned` Whether the format can lend a slice depends on the input, not on the attribute: - **Escape sequences.** In JSON, `"line\nbreak"` is stored as the characters `\` and `n`, but the value contains a newline. No slice of the input equals the decoded text, so serde_json builds a `String` and the field becomes `Cow::Owned`. - **Streaming input.** `serde_json::from_reader` reads through a buffer that is reused, so it can never lend `&'de str`. It also requires `T: DeserializeOwned`, which a `#[serde(borrow)]` struct does not satisfy; rustc rejects the call with "implementation of `Deserialize` is not general enough". ## A trace through the example The code example deserializes the same struct twice: 1. Input `{"plain":"abc","zero_copy":"abc"}` with `from_str`. The `plain` field goes through serde's ordinary `Cow` impl, so serde_json's string is copied into a `String` and the field is `Owned`. The `zero_copy` field goes through the borrowing visitor; serde_json offers a borrowed slice because `abc` has no escapes, and the field is `Borrowed`, pointing into `json`. 2. Input with `"line\nbreak"` for `zero_copy`. serde_json must turn the two characters `\` and `n` into one newline, so it decodes into a scratch buffer and offers a temporary `&str`; the visitor copies it and the field is `Owned`. Both structs type-check as `Event<'_>` borrowing from their input strings, so neither may outlive the `json` or `escaped` binding even when every field happens to be `Owned`: the type, not the runtime variant, decides how long the value may live. ## Field types compared | Field type | No escapes, `from_str` | With escapes, `from_str` | `from_reader` | |---|---|---|---| | `String` | allocates | allocates | works | | `Cow<'a, str>` | `Owned`, allocates | `Owned`, allocates | works | | `Cow<'a, str>` + `#[serde(borrow)]` | `Borrowed`, no allocation | `Owned`, allocates | does not compile | | `&'a str` | borrows | error: expected a borrowed string | does not compile | The last row is the reason `Cow` exists in deserialized types. A `&'a str` field turns an escaped string into a runtime error: serde_json reports `invalid type: string "a\nb", expected a borrowed string`. `Cow` with `#[serde(borrow)]` borrows when it can and quietly allocates when it must. On the way out, serde's `Serialize` impl for `Cow` simply delegates to the inner value, so the variant leaves no trace in the output. ## Detaching to `'static` A borrowing struct cannot outlive its input buffer. To keep it, convert each field with `Cow::into_owned`, which moves an `Owned` value out for free and copies a `Borrowed` one: ```rust impl Event<'_> { fn into_static(self) -> Event<'static> { Event { name: Cow::Owned(self.name.into_owned()) } } } ``` The result holds only `Cow::Owned` values, so its lifetime can be `'static` and it can be stored in a cache or sent to another thread. ## Review checklist - A `Cow<'a, str>` field without `#[serde(borrow)]` never borrows; either add the attribute or use `String` and say what you mean. - With the attribute, expect `Borrowed` only from in-memory input such as `from_str` or `from_slice`, and only for unescaped strings. - Never choose `&'a str` for text that may contain escapes. - Convert to an owned form before a borrowed value outlives its buffer. The general rules for the `'de` lifetime and `#[serde(borrow)]` on other types belong with the serde data model; what is specific here is how `Cow`'s two variants absorb the difference between borrowable and non-borrowable input.

  • Why not make the field `&'a str` and avoid `Cow` entirely?
    A `&'a str` field can only point into the input, so it works only when every string in it can be borrowed. A string with an escape sequence decodes to text that exists nowhere in the input, and serde_json fails with "invalid type: string ..., expected a borrowed string". A `#[serde(borrow)]` `Cow<'a, str>` borrows in the same cases and falls back to `Cow::Owned` instead of failing.
  • How do you keep a deserialized `Event<'a>` after the input buffer is dropped?
    Convert each `Cow` field with `into_owned()` and rebuild the struct as `Event<'static>`, which holds only `Cow::Owned` values. Alternatively, deserialize an owned type from the start. A struct with a `#[serde(borrow)]` field is not `DeserializeOwned`, so `serde_json::from_reader` rejects it: rustc reports that the implementation of `Deserialize` is not general enough.

  • A Cow<'a, str> field borrows from the JSON input automatically.
  • #[serde(borrow)] guarantees every Cow field comes out Borrowed.
  • &'a str fields are strictly better because they never allocate.
  • serde_json::from_reader can fill a #[serde(borrow)] struct.
  • Serializing a Cow records whether it was borrowed or owned.