Arc<Mutex>

Guides

Rust walkthroughs

← Back to all guides

How does serde::de::DeserializeSeed::deserialize enable context-aware deserialization with external state?

DeserializeSeed::deserialize allows deserializing values with access to external context that isn't present in the serialized data itself, passing a seed value through the deserialization process to provide state, configuration, or contextual information needed to properly construct the deserialized type. Unlike regular Deserialize::deserialize which works purely from the input data, DeserializeSeed can carry arbitrary context—database connections, caches, registries, or configuration—that the deserialized type needs during construction. The seed is passed to the deserialize method and flows through the deserializer to any type that implements DeserializeSeed.

Basic DeserializeSeed Usage

use serde::de::{DeserializeSeed, Deserialize, Deserializer, Visitor};
use std::marker::PhantomData;
 
// A seed that provides context during deserialization
struct ContextSeed<'a, T> {
    context: &'a str,
    _marker: PhantomData<T>,
}
 
impl<'de, T> DeserializeSeed<'de> for ContextSeed<'_, T>
where
    T: Deserialize<'de>,
{
    type Value = T;
 
    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
    where
        D: Deserializer<'de>,
    {
        // The seed can use context before/after deserialization
        println!("Deserializing with context: {}", self.context);
        T::deserialize(deserializer)
    }
}
 
fn main() {
    let json = "\"hello\"";
    let seed = ContextSeed {
        context: "my_context",
        _marker: PhantomData::<String>,
    };
    
    let result: String = serde_json::from_str(json).unwrap();
    println!("Result: {}", result);
}

DeserializeSeed provides a way to pass context alongside deserialization.

The DeserializeSeed Trait Definition

use serde::de::{DeserializeSeed, Deserializer};
 
// The core trait
pub trait DeserializeSeed<'de>: Sized {
    // The type produced by deserialization
    type Value;
 
    // Deserialize using the given deserializer
    // Self is consumed, allowing the seed to carry owned data
    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
    where
        D: Deserializer<'de>;
}
 
// Unlike Deserialize, DeserializeSeed:
// 1. Takes self by value (can carry owned context)
// 2. Has an associated Value type
// 3. Can use context before calling inner deserialize
// 4. Is typically implemented for specific types with context

The trait allows carrying context through deserialization.

Seed with Registry Lookup

use serde::de::{DeserializeSeed, Deserializer, Visitor, Error};
use std::collections::HashMap;
 
// A registry of named items
struct Registry {
    items: HashMap<String, i32>,
}
 
impl Registry {
    fn new() -> Self {
        let mut items = HashMap::new();
        items.insert("alpha".to_string(), 1);
        items.insert("beta".to_string(), 2);
        items.insert("gamma".to_string(), 3);
        Self { items }
    }
}
 
// A type that references items by name
struct Item {
    name: String,
    value: i32,
}
 
// Seed that resolves names from registry
struct ItemSeed<'a> {
    registry: &'a Registry,
}
 
impl<'de> DeserializeSeed<'de> for ItemSeed<'_> {
    type Value = Item;
 
    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
    where
        D: Deserializer<'de>,
    {
        // First deserialize just the name
        let name = String::deserialize(deserializer)?;
        
        // Then look up value from registry
        let value = self.registry.items.get(&name)
            .ok_or_else(|| D::Error::custom(format!("Unknown item: {}", name)))?;
        
        Ok(Item {
            name,
            value: *value,
        })
    }
}
 
fn main() {
    let registry = Registry::new();
    let json = "\"beta\"";
    
    let seed = ItemSeed { registry: &registry };
    let deserializer = &mut serde_json::Deserializer::from_str(json);
    
    let item: Item = seed.deserialize(deserializer).unwrap();
    println!("Item: {} = {}", item.name, item.value);
    // Output: Item: beta = 2
}

The seed can resolve references from an external registry.

Deserializing Structured Data with Context

use serde::de::{DeserializeSeed, Deserializer, Visitor, MapAccess};
use std::collections::HashMap;
 
// Configuration that affects deserialization
struct Config {
    default_value: i32,
    allow_missing: bool,
}
 
// Data structure to deserialize
struct Record {
    id: String,
    value: i32,
}
 
// Seed with config context
struct RecordSeed<'a> {
    config: &'a Config,
}
 
impl<'de> DeserializeSeed<'de> for RecordSeed<'_> {
    type Value = Record;
 
    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
    where
        D: Deserializer<'de>,
    {
        // Custom visitor that uses config
        struct RecordVisitor<'a> {
            config: &'a Config,
        }
 
        impl<'de, 'a> Visitor<'de> for RecordVisitor<'a> {
            type Value = Record;
 
            fn expecting(&self, fmt: &mut std::fmt::Formatter) -> std::fmt::Result {
                write!(fmt, "a record with id and optional value")
            }
 
            fn visit_map<M>(self, mut map: M) -> Result<Record, M::Error>
            where
                M: MapAccess<'de>,
            {
                let mut id = None;
                let mut value = None;
 
                while let Some(key) = map.next_key::<String>()? {
                    match key.as_str() {
                        "id" => id = Some(map.next_value()?),
                        "value" => value = Some(map.next_value()?),
                        _ => { map.next_value::<serde::de::IgnoredAny>()?; }
                    }
                }
 
                let id = id.ok_or_else(|| serde::de::Error::missing_field("id"))?;
                
                // Use config for missing value handling
                let value = match (value, self.config.allow_missing) {
                    (Some(v), _) => v,
                    (None, true) => self.config.default_value,
                    (None, false) => return Err(serde::de::Error::missing_field("value")),
                };
 
                Ok(Record { id, value })
            }
        }
 
        deserializer.deserialize_map(RecordVisitor { config: self.config })
    }
}
 
fn main() {
    let config = Config {
        default_value: 0,
        allow_missing: true,
    };
    
    let json = r#"{"id": "test"}"#;  // Missing value
    
    let seed = RecordSeed { config: &config };
    let deserializer = &mut serde_json::Deserializer::from_str(json);
    
    let record: Record = seed.deserialize(deserializer).unwrap();
    println!("Record: {} = {}", record.id, record.value);
    // Uses default value from config
}

The seed passes configuration to control deserialization behavior.

Recursive Structures with Context

use serde::de::{DeserializeSeed, Deserializer, SeqAccess, Visitor};
use std::collections::HashMap;
 
// Recursive tree structure
enum Tree {
    Leaf(i32),
    Branch { children: Vec<Tree> },
}
 
// Context for deserializing trees (e.g., depth limit)
struct TreeContext {
    max_depth: usize,
    current_depth: usize,
}
 
impl TreeContext {
    fn child_context(&self) -> Self {
        TreeContext {
            max_depth: self.max_depth,
            current_depth: self.current_depth + 1,
        }
    }
}
 
struct TreeSeed<'a> {
    context: &'a TreeContext,
}
 
impl<'de> DeserializeSeed<'de> for TreeSeed<'_> {
    type Value = Tree;
 
    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
    where
        D: Deserializer<'de>,
    {
        struct TreeVisitor<'a> {
            context: &'a TreeContext,
        }
 
        impl<'de, 'a> Visitor<'de> for TreeVisitor<'a> {
            type Value = Tree;
 
            fn expecting(&self, fmt: &mut std::fmt::Formatter) -> std::fmt::Result {
                write!(fmt, "a number or array of trees")
            }
 
            fn visit_i64<E>(self, value: i64) -> Result<Tree, E>
            where
                E: serde::de::Error,
            {
                Ok(Tree::Leaf(value as i32))
            }
 
            fn visit_seq<S>(self, mut seq: S) -> Result<Tree, S::Error>
            where
                S: SeqAccess<'de>,
            {
                if self.context.current_depth >= self.context.max_depth {
                    return Err(serde::de::Error::custom("maximum depth exceeded"));
                }
 
                let mut children = Vec::new();
                let child_context = self.context.child_context();
                
                while let Some(child) = seq.next_element_seed(TreeSeed { context: &child_context })? {
                    children.push(child);
                }
 
                Ok(Tree::Branch { children })
            }
        }
 
        deserializer.deserialize_any(TreeVisitor { context: self.context })
    }
}
 
fn main() {
    let context = TreeContext {
        max_depth: 3,
        current_depth: 0,
    };
    
    let json = "[1, [2, [3, [4]]]]";
    let seed = TreeSeed { context: &context };
    let deserializer = &mut serde_json::Deserializer::from_str(json);
    
    let tree: Tree = seed.deserialize(deserializer).unwrap();
    println!("Tree deserialized with depth limit");
}

The seed can enforce constraints like depth limits on recursive structures.

Database Context for Resolution

use serde::de::{DeserializeSeed, Deserializer, Error};
use std::collections::HashMap;
 
// Simulated database
struct Database {
    users: HashMap<u64, String>,
}
 
impl Database {
    fn new() -> Self {
        let mut users = HashMap::new();
        users.insert(1, "Alice".to_string());
        users.insert(2, "Bob".to_string());
        users.insert(3, "Charlie".to_string());
        Database { users }
    }
}
 
// A struct that references database entities
struct Post {
    author_id: u64,
    author_name: String,  // Resolved from database
    content: String,
}
 
struct PostSeed<'a> {
    db: &'a Database,
}
 
impl<'de> DeserializeSeed<'de> for PostSeed<'_> {
    type Value = Post;
 
    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
    where
        D: Deserializer<'de>,
    {
        // Use serde's derive for partial deserialization
        #[derive(serde::Deserialize)]
        struct PostData {
            author_id: u64,
            content: String,
        }
 
        let data = PostData::deserialize(deserializer)?;
        
        // Resolve author name from database
        let author_name = self.db.users.get(&data.author_id)
            .cloned()
            .ok_or_else(|| D::Error::custom(format!("Unknown author: {}", data.author_id)))?;
 
        Ok(Post {
            author_id: data.author_id,
            author_name,
            content: data.content,
        })
    }
}
 
fn main() {
    let db = Database::new();
    let json = r#"{"author_id": 1, "content": "Hello, world!"}"";
    
    let seed = PostSeed { db: &db };
    let deserializer = &mut serde_json::Deserializer::from_str(json);
    
    let post: Post = seed.deserialize(deserializer).unwrap();
    println!("{}: {}", post.author_name, post.content);
    // Output: Alice: Hello, world!
}

The seed can resolve references from a database during deserialization.

Type Registry for Polymorphic Deserialization

use serde::de::{DeserializeSeed, Deserializer, Error};
use std::collections::HashMap;
 
// Trait object deserialization requires registry
trait Animal: std::fmt::Debug {
    fn speak(&self) -> String;
}
 
#[derive(Debug)]
struct Dog { name: String }
impl Animal for Dog {
    fn speak(&self) -> String { format!("{} barks!", self.name) }
}
 
#[derive(Debug)]
struct Cat { name: String }
impl Animal for Cat {
    fn speak(&self) -> String { format!("{} meows!", self.name) }
}
 
// Registry mapping type names to constructors
struct AnimalRegistry {
    constructors: HashMap<String, fn(String) -> Box<dyn Animal>>,
}
 
impl AnimalRegistry {
    fn new() -> Self {
        let mut constructors: HashMap<String, fn(String) -> Box<dyn Animal>> = HashMap::new();
        constructors.insert("dog".to_string(), |name| Box::new(Dog { name }));
        constructors.insert("cat".to_string(), |name| Box::new(Cat { name }));
        AnimalRegistry { constructors }
    }
    
    fn create(&self, type_name: &str, name: String) -> Option<Box<dyn Animal>> {
        self.constructors.get(type_name).map(|f| f(name))
    }
}
 
// Seed with type registry
struct AnimalSeed<'a> {
    registry: &'a AnimalRegistry,
}
 
#[derive(serde::Deserialize)]
struct AnimalData {
    type_name: String,
    name: String,
}
 
impl<'de> DeserializeSeed<'de> for AnimalSeed<'_> {
    type Value = Box<dyn Animal>;
 
    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
    where
        D: Deserializer<'de>,
    {
        let data = AnimalData::deserialize(deserializer)?;
        
        self.registry.create(&data.type_name, data.name)
            .ok_or_else(|| D::Error::custom(format!("Unknown animal type: {}", data.type_name)))
    }
}
 
fn main() {
    let registry = AnimalRegistry::new();
    let json = r#"{"type_name": "dog", "name": "Rex"}"#;
    
    let seed = AnimalSeed { registry: &registry };
    let deserializer = &mut serde_json::Deserializer::from_str(json);
    
    let animal: Box<dyn Animal> = seed.deserialize(deserializer).unwrap();
    println!("{:?}", animal);
    println!("{}", animal.speak());
}

Seeds enable deserializing trait objects via type registries.

Comparison with Regular Deserialize

use serde::de::{DeserializeSeed, Deserialize, Deserializer};
 
// Regular Deserialize: No context
struct SimpleData {
    value: i32,
}
 
impl<'de> Deserialize<'de> for SimpleData {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        // Can only use data from input
        let value = i32::deserialize(deserializer)?;
        Ok(SimpleData { value })
    }
}
 
// DeserializeSeed: With context
struct ContextualData {
    value: i32,
    multiplier: i32,  // From context, not input
}
 
struct ContextualSeed {
    multiplier: i32,
}
 
impl<'de> DeserializeSeed<'de> for ContextualSeed {
    type Value = ContextualData;
 
    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
    where
        D: Deserializer<'de>,
    {
        // Can use context during deserialization
        let value = i32::deserialize(deserializer)?;
        Ok(ContextualData {
            value,
            multiplier: self.multiplier,
        })
    }
}
 
fn main() {
    // Regular Deserialize: context-free
    let simple: SimpleData = serde_json::from_str("42").unwrap();
    println!("Simple: {}", simple.value);
    
    // DeserializeSeed: with context
    let seed = ContextualSeed { multiplier: 10 };
    let deserializer = &mut serde_json::Deserializer::from_str("42");
    let contextual: ContextualData = seed.deserialize(deserializer).unwrap();
    println!("Contextual: {} (multiplier: {})", contextual.value, contextual.multiplier);
}

DeserializeSeed adds context that regular Deserialize cannot access.

Passing Context Through Nested Deserialization

use serde::de::{DeserializeSeed, Deserializer, MapAccess, Visitor};
 
// Configuration that flows through entire deserialization
struct AppContext {
    version: String,
    strict: bool,
}
 
// Outer structure
struct Document {
    version: String,
    items: Vec<Item>,
}
 
struct Item {
    name: String,
    verified: bool,
}
 
struct DocumentSeed<'a> {
    context: &'a AppContext,
}
 
struct ItemSeed<'a> {
    context: &'a AppContext,
}
 
impl<'de> DeserializeSeed<'de> for DocumentSeed<'_> {
    type Value = Document;
 
    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
    where
        D: Deserializer<'de>,
    {
        #[derive(serde::Deserialize)]
        struct DocumentData {
            version: String,
            items: Vec<ItemData>,
        }
        
        #[derive(serde::Deserialize)]
        struct ItemData {
            name: String,
            verified: Option<bool>,
        }
 
        let data = DocumentData::deserialize(deserializer)?;
        
        // Transform using context
        let items = data.items.into_iter().map(|item| {
            Item {
                name: item.name,
                verified: item.verified.unwrap_or(!self.context.strict),
            }
        }).collect();
 
        Ok(Document {
            version: data.version,
            items,
        })
    }
}
 
fn main() {
    let context = AppContext {
        version: "1.0".to_string(),
        strict: true,
    };
    
    let json = r#"{"version": "1.0", "items": [{"name": "a"}, {"name": "b", "verified": true}]}"#;
    
    let seed = DocumentSeed { context: &context };
    let deserializer = &mut serde_json::Deserializer::from_str(json);
    
    let doc: Document = seed.deserialize(deserializer).unwrap();
    println!("Document version: {}", doc.version);
    for item in &doc.items {
        println!("  {} (verified: {})", item.name, item.verified);
    }
}

Context flows through the entire deserialization process.

Seed with Cache for Deduplication

use serde::de::{DeserializeSeed, Deserializer};
use std::collections::HashMap;
use std::rc::Rc;
 
// Interned strings - deduplicated
struct InternedStrings {
    cache: HashMap<String, Rc<str>>,
}
 
impl InternedStrings {
    fn new() -> Self {
        InternedStrings { cache: HashMap::new() }
    }
    
    fn intern(&mut self, s: String) -> Rc<str> {
        self.cache.entry(s.clone())
            .or_insert_with(|| Rc::from(s.as_str()))
            .clone()
    }
}
 
struct InternedStringSeed<'a> {
    cache: &'a mut InternedStrings,
}
 
impl<'de> DeserializeSeed<'de> for InternedStringSeed<'_> {
    type Value = Rc<str>;
 
    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
    where
        D: Deserializer<'de>,
    {
        let s = String::deserialize(deserializer)?;
        Ok(self.cache.intern(s))
    }
}
 
fn main() {
    let mut cache = InternedStrings::new();
    
    // Deserialize with deduplication
    let json = r#"["hello", "world", "hello"]"#;
    let deserializer = &mut serde_json::Deserializer::from_str(json);
    
    let arr: Vec<Rc<str>> = serde::de::SeqAccess::new(deserializer)
        .and_then(|mut seq| {
            let mut results = Vec::new();
            while let Some(item) = seq.next_element_seed(InternedStringSeed { cache: &mut cache })? {
                results.push(item);
            }
            Ok(results)
        })
        .unwrap();
    
    // First and third elements are the same Rc
    println!("First: {}", arr[0]);
    println!("Deduplicated: {}", Rc::ptr_eq(&arr[0], &arr[2]));
}

Seeds enable caching and deduplication during deserialization.

Implementing Clone for Seeds

use serde::de::{DeserializeSeed, Deserializer};
 
// Seeds often need Clone for complex deserializations
#[derive(Clone)]
struct MultiplierSeed {
    multiplier: i32,
}
 
impl<'de> DeserializeSeed<'de> for MultiplierSeed {
    type Value = i32;
 
    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
    where
        D: Deserializer<'de>,
    {
        let value = i32::deserialize(deserializer)?;
        Ok(value * self.multiplier)
    }
}
 
// Clone is needed when seed is used multiple times
fn deserialize_array<'de, D>(deserializer: D, seed: MultiplierSeed) -> Result<Vec<i32>, D::Error>
where
    D: Deserializer<'de>,
{
    use serde::de::{SeqAccess, Visitor};
    
    struct ArrayVisitor {
        seed: MultiplierSeed,
    }
 
    impl<'de> Visitor<'de> for ArrayVisitor {
        type Value = Vec<i32>;
 
        fn expecting(&self, fmt: &mut std::fmt::Formatter) -> std::fmt::Result {
            write!(fmt, "an array of integers")
        }
 
        fn visit_seq<S>(self, mut seq: S) -> Result<Vec<i32>, S::Error>
        where
            S: SeqAccess<'de>,
        {
            let mut results = Vec::new();
            while let Some(item) = seq.next_element_seed(self.seed.clone())? {
                results.push(item);
            }
            Ok(results)
        }
    }
 
    deserializer.deserialize_seq(ArrayVisitor { seed })
}
 
fn main() {
    let seed = MultiplierSeed { multiplier: 10 };
    let json = r#"[1, 2, 3]"#;
    let deserializer = &mut serde_json::Deserializer::from_str(json);
    
    let values: Vec<i32> = seed.deserialize(deserializer).unwrap();
    println!("Multiplied values: {:?}", values);
}

Seeds often need Clone when used in sequence deserialization.

Invariant Lifetime Pattern

use serde::de::{DeserializeSeed, Deserializer};
use std::marker::PhantomData;
 
// Invariant lifetime prevents misuse
pub struct InvariantSeed<'a, T> {
    context: &'a T,
    // Invariant lifetime
    _marker: PhantomData<fn(&'a T) -> &'a T>,
}
 
impl<'de, T> DeserializeSeed<'de> for InvariantSeed<'_, T>
where
    T: 'de,
{
    type Value = &'de T;
 
    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
    where
        D: Deserializer<'de>,
    {
        // This pattern ensures lifetime safety
        unimplemented!("Example pattern only")
    }
}
 
// The invariant lifetime ensures the context lives long enough
// for the entire deserialization process

Invariant lifetimes ensure context validity during deserialization.

Key Points

fn key_points() {
    // 1. DeserializeSeed provides context during deserialization
    // 2. Takes self by value, allowing owned context
    // 3. Has associated Value type for output
    // 4. Can carry registries, databases, caches
    // 5. Enables resolution of external references
    // 6. Supports configuration-driven deserialization
    // 7. Allows polymorphic deserialization via type registry
    // 8. Can enforce constraints like depth limits
    // 9. Enables deduplication/caching during deserialization
    // 10. Passes context through nested deserialization
    // 11. Often requires Clone for sequence handling
    // 12. Invariant lifetimes ensure safety
    // 13. Used with Deserializer::deserialize_seed
    // 14. Can transform input before returning
    // 15. Enables default values from context
    // 16. Supports validation with external state
    // 17. Can inject dependencies during construction
    // 18. Regular Deserialize has no context access
    // 19. Seeds implement DeserializeSeed trait
    // 20. Critical for advanced deserialization patterns
}

Key insight: DeserializeSeed::deserialize bridges the gap between pure deserialization (which only sees the input data) and context-aware construction (which needs external state). By passing a seed value through the deserialization process, you can resolve references from databases, apply configuration defaults, enforce constraints, maintain caches, and implement type registries for polymorphic deserialization. The seed is consumed during deserialization, which allows it to carry owned data that gets transferred to the resulting value. This pattern is essential when deserialized types need dependencies or configuration that aren't present in the serialized format, enabling dependency injection patterns during deserialization that would otherwise be impossible with standard Deserialize.