Enum FieldValue 

pub enum FieldValue {
    Bool(bool),
    I8(i8),
    I16(i16),
    I32(i32),
    I64(i64),
    U8(u8),
    U16(u16),
    U32(u32),
    U64(u64),
    Usize(usize),
    F32(f32),
    F64(f64),
    String(String),
    Bytes(Vec<u8>),
    JsonObject(String),
    BinaryObject(Vec<u8>),
    Array(Vec<FieldValue>),
    Optional(Option<Box<FieldValue>>),
    Object(HashMap<String, FieldValue>),
    Enum {
        variant: String,
        data: Option<Box<FieldValue>>,
    },
}

Universal type-safe container for all serializable field values

This enum provides a unified representation for all possible serializable values in the Train Station serialization system. It maintains type safety while enabling uniform handling in the serialization pipeline, supporting both primitive types and complex data structures.

The enum uses Rust’s tagged union optimization for efficient memory layout, with larger variants (Optional, Enum) using heap allocation to minimize the base enum size. All variants support comprehensive validation and type conversion.

Variants

Primitive Types

• Bool(bool) - Boolean true/false values
• I8(i8) - 8-bit signed integers (-128 to 127)
• I16(i16) - 16-bit signed integers (-32,768 to 32,767)
• I32(i32) - 32-bit signed integers (-2^31 to 2^31-1)
• I64(i64) - 64-bit signed integers (-2^63 to 2^63-1)
• U8(u8) - 8-bit unsigned integers (0 to 255)
• U16(u16) - 16-bit unsigned integers (0 to 65,535)
• U32(u32) - 32-bit unsigned integers (0 to 2^32-1)
• U64(u64) - 64-bit unsigned integers (0 to 2^64-1)
• Usize(usize) - Platform-specific size integers
• F32(f32) - 32-bit floating point numbers
• F64(f64) - 64-bit floating point numbers
• String(String) - UTF-8 encoded text strings

Complex Types

• Bytes(Vec<u8>) - Raw binary data arrays
• JsonObject(String) - JSON-serialized object strings
• BinaryObject(Vec<u8>) - Binary-serialized object data
• Array(Vec<FieldValue>) - Heterogeneous value arrays
• Optional(Option<Box<FieldValue>>) - Nullable field values
• Object(HashMap<String, FieldValue>) - Key-value object maps
• Enum { variant: String, data: Option<Box<FieldValue>> } - Enum variants with optional data

Type Conversion

The enum provides comprehensive type conversion capabilities:

• Numeric conversions: Automatic conversion between compatible integer and float types
• Range validation: Overflow/underflow checking for all conversions
• Sign validation: Proper handling of signed/unsigned type conversions
• String parsing: Hex string parsing for byte array conversion

Error Handling

All conversion methods return SerializationResult<T> with detailed error information:

• Type mismatch errors: Clear indication of expected vs actual types
• Range validation errors: Specific overflow/underflow details
• Parsing errors: Detailed hex string parsing failure information
• Field context: Error messages include field names for debugging

Performance Characteristics

• Zero-copy operations: Small variants stored inline for maximum performance
• Efficient conversions: Optimized type conversion with minimal allocations
• Memory layout: Tagged union optimization for minimal memory overhead
• Validation speed: Fast type checking with early return on mismatches

Thread Safety

This type is thread-safe and can be shared between threads. All variants implement Clone and PartialEq for flexible usage patterns.

Variants

Bool(bool)

Boolean true/false values

I8(i8)

8-bit signed integers (-128 to 127)

I16(i16)

16-bit signed integers (-32,768 to 32,767)

I32(i32)

32-bit signed integers (-2^31 to 2^31-1)

I64(i64)

64-bit signed integers (-2^63 to 2^63-1)

U8(u8)

8-bit unsigned integers (0 to 255)

U16(u16)

16-bit unsigned integers (0 to 65,535)

U32(u32)

32-bit unsigned integers (0 to 2^32-1)

U64(u64)

64-bit unsigned integers (0 to 2^64-1)

Usize(usize)

Platform-specific size integers for array lengths and indices

F32(f32)

32-bit floating point numbers with single precision

F64(f64)

64-bit floating point numbers with double precision

String(String)

UTF-8 encoded text strings

Bytes(Vec<u8>)

Raw binary data arrays for efficient storage

JsonObject(String)

JSON-serialized object strings for human-readable format

BinaryObject(Vec<u8>)

Binary-serialized object data for compact storage

Array(Vec<FieldValue>)

Heterogeneous arrays of field values

Optional(Option<Box<FieldValue>>)

Nullable field values that may be None

Object(HashMap<String, FieldValue>)

Key-value object maps for structured data

Enum

Enum variants with optional associated data

Supports three enum variant types:

• Unit variant: Enum { variant: "VariantName", data: None }
• Tuple variant: Enum { variant: "VariantName", data: Some(Array([...])) }
• Struct variant: Enum { variant: "VariantName", data: Some(Object({...})) }

Fields

variant: String

The name of the enum variant

data: Option<Box<FieldValue>>

Optional associated data for the variant (boxed for memory efficiency)

Implementations

impl FieldValue

pub fn from_bool(value: bool) -> Self

Creates a boolean field value

Arguments

• value - Boolean value to store

Returns

A FieldValue::Bool variant containing the boolean value

pub fn from_i8(value: i8) -> Self

Creates an 8-bit signed integer field value

Arguments

• value - 8-bit signed integer to store

Returns

A FieldValue::I8 variant containing the integer value

pub fn from_i16(value: i16) -> Self

Creates a 16-bit signed integer field value

Arguments

• value - 16-bit signed integer to store

Returns

A FieldValue::I16 variant containing the integer value

pub fn from_i32(value: i32) -> Self

Creates a 32-bit signed integer field value

Arguments

• value - 32-bit signed integer to store

Returns

A FieldValue::I32 variant containing the integer value

pub fn from_i64(value: i64) -> Self

Creates a 64-bit signed integer field value

Arguments

• value - 64-bit signed integer to store

Returns

A FieldValue::I64 variant containing the integer value

pub fn from_u8(value: u8) -> Self

Creates an 8-bit unsigned integer field value

Arguments

• value - 8-bit unsigned integer to store

Returns

A FieldValue::U8 variant containing the integer value

pub fn from_u16(value: u16) -> Self

Creates a 16-bit unsigned integer field value

Arguments

• value - 16-bit unsigned integer to store

Returns

A FieldValue::U16 variant containing the integer value

pub fn from_u32(value: u32) -> Self

Creates a 32-bit unsigned integer field value

Arguments

• value - 32-bit unsigned integer to store

Returns

A FieldValue::U32 variant containing the integer value

pub fn from_u64(value: u64) -> Self

Creates a 64-bit unsigned integer field value

Arguments

• value - 64-bit unsigned integer to store

Returns

A FieldValue::U64 variant containing the integer value

pub fn from_usize(value: usize) -> Self

Creates a platform-specific size integer field value

Arguments

• value - Platform-specific size integer to store

Returns

A FieldValue::Usize variant containing the size value

pub fn from_f32(value: f32) -> Self

Creates a 32-bit floating point field value

Arguments

• value - 32-bit floating point number to store

Returns

A FieldValue::F32 variant containing the float value

pub fn from_f64(value: f64) -> Self

Creates a 64-bit floating point field value

Arguments

• value - 64-bit floating point number to store

Returns

A FieldValue::F64 variant containing the float value

pub fn from_string(value: String) -> Self

Creates a string field value from an owned string

Arguments

• value - Owned string to store

Returns

A FieldValue::String variant containing the string value

Examples found in repository

examples/serialization/error_handling.rs (line 88)

    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for VersionedData {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize VersionedData from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize VersionedData from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for VersionedData, found {}",
                value.type_name()
            ),
        })
    }
}

/// Validated user input with constraints
#[derive(Debug, Clone, PartialEq)]
pub struct ValidatedUserInput {
    pub username: String,
    pub email: String,
    pub age: u16,
    pub preferences: HashMap<String, String>,
}

impl StructSerializable for ValidatedUserInput {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("username", &self.username)
            .field("email", &self.email)
            .field("age", &self.age)
            .field("preferences", &self.preferences)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let username: String = deserializer.field("username")?;
        let email: String = deserializer.field("email")?;
        let age: u16 = deserializer.field("age")?;
        let preferences: HashMap<String, String> = deserializer.field("preferences")?;

        // Validate username
        if username.is_empty() || username.len() > 50 {
            return Err(SerializationError::ValidationFailed {
                field: "username".to_string(),
                message: "Username must be 1-50 characters long".to_string(),
            });
        }

        if !username
            .chars()
            .all(|c| c.is_alphanumeric() || c == '_' || c == '-')
        {
            return Err(SerializationError::ValidationFailed {
                field: "username".to_string(),
                message:
                    "Username can only contain alphanumeric characters, underscores, and hyphens"
                        .to_string(),
            });
        }

        // Validate email (basic check)
        if !email.contains('@') || !email.contains('.') || email.len() < 5 {
            return Err(SerializationError::ValidationFailed {
                field: "email".to_string(),
                message: "Invalid email format".to_string(),
            });
        }

        // Validate age
        if !(13..=120).contains(&age) {
            return Err(SerializationError::ValidationFailed {
                field: "age".to_string(),
                message: "Age must be between 13 and 120".to_string(),
            });
        }

        // Validate preferences
        if preferences.len() > 20 {
            return Err(SerializationError::ValidationFailed {
                field: "preferences".to_string(),
                message: "Too many preferences (maximum 20)".to_string(),
            });
        }

        for (key, value) in &preferences {
            if key.len() > 50 || value.len() > 200 {
                return Err(SerializationError::ValidationFailed {
                    field: "preferences".to_string(),
                    message: format!("Preference key/value too long: {}", key),
                });
            }
        }

        Ok(ValidatedUserInput {
            username,
            email,
            age,
            preferences,
        })
    }
}

impl ToFieldValue for ValidatedUserInput {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for ValidatedUserInput {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize ValidatedUserInput from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!(
                        "Failed to deserialize ValidatedUserInput from binary: {}",
                        e
                    ),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for ValidatedUserInput, found {}",
                value.type_name()
            ),
        })
    }
}

/// Recovery helper for handling partial data
#[derive(Debug, Clone, PartialEq)]
pub struct RecoverableData {
    pub critical_field: String,
    pub important_field: Option<String>,
    pub optional_field: Option<String>,
    pub metadata: HashMap<String, String>,
}

impl StructSerializable for RecoverableData {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("critical_field", &self.critical_field)
            .field("important_field", &self.important_field)
            .field("optional_field", &self.optional_field)
            .field("metadata", &self.metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        // Critical field - must exist
        let critical_field = deserializer.field("critical_field")?;

        // Important field - try to recover if missing
        let important_field = deserializer.field_optional("important_field")?;

        // Optional field - graceful fallback
        let optional_field = deserializer.field_optional("optional_field")?;

        // Metadata - recover what we can
        let metadata = deserializer.field_or("metadata", HashMap::new())?;

        Ok(RecoverableData {
            critical_field,
            important_field,
            optional_field,
            metadata,
        })
    }
}

impl ToFieldValue for RecoverableData {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }

examples/serialization/json_vs_binary.rs (line 81)

    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for PerformanceMetrics {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize PerformanceMetrics from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!(
                        "Failed to deserialize PerformanceMetrics from binary: {}",
                        e
                    ),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for PerformanceMetrics, found {}",
                value.type_name()
            ),
        })
    }
}

/// Large dataset for performance testing
#[derive(Debug, Clone, PartialEq)]
pub struct LargeDataset {
    pub name: String,
    pub values: Vec<f32>, // Changed from f64 to f32 (supported)
    pub labels: Vec<String>,
    pub feature_count: usize, // Simplified from Vec<Vec<f32>> to just a count
    pub feature_dimension: usize, // Store dimensions separately
    pub metadata: HashMap<String, String>,
    pub timestamp_count: usize, // Simplified from Vec<u64> to just count
}

impl StructSerializable for LargeDataset {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("values", &self.values)
            .field("labels", &self.labels)
            .field("feature_count", &self.feature_count)
            .field("feature_dimension", &self.feature_dimension)
            .field("metadata", &self.metadata)
            .field("timestamp_count", &self.timestamp_count)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let values = deserializer.field("values")?;
        let labels = deserializer.field("labels")?;
        let feature_count = deserializer.field("feature_count")?;
        let feature_dimension = deserializer.field("feature_dimension")?;
        let metadata = deserializer.field("metadata")?;
        let timestamp_count = deserializer.field("timestamp_count")?;

        Ok(LargeDataset {
            name,
            values,
            labels,
            feature_count,
            feature_dimension,
            metadata,
            timestamp_count,
        })
    }
}

impl ToFieldValue for LargeDataset {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for LargeDataset {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize LargeDataset from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize LargeDataset from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for LargeDataset, found {}",
                value.type_name()
            ),
        })
    }
}

/// Configuration data (typical JSON use case)
#[derive(Debug, Clone, PartialEq)]
pub struct Configuration {
    pub version: String,
    pub debug_enabled: bool,
    pub log_level: String,
    pub database_settings: HashMap<String, String>,
    pub feature_flags_enabled: bool, // Simplified from HashMap<String, bool>
    pub max_connections: f32,        // Simplified from HashMap<String, f64>
    pub timeout_seconds: f32,
}

impl StructSerializable for Configuration {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("version", &self.version)
            .field("debug_enabled", &self.debug_enabled)
            .field("log_level", &self.log_level)
            .field("database_settings", &self.database_settings)
            .field("feature_flags_enabled", &self.feature_flags_enabled)
            .field("max_connections", &self.max_connections)
            .field("timeout_seconds", &self.timeout_seconds)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let version = deserializer.field("version")?;
        let debug_enabled = deserializer.field("debug_enabled")?;
        let log_level = deserializer.field("log_level")?;
        let database_settings = deserializer.field("database_settings")?;
        let feature_flags_enabled = deserializer.field("feature_flags_enabled")?;
        let max_connections = deserializer.field("max_connections")?;
        let timeout_seconds = deserializer.field("timeout_seconds")?;

        Ok(Configuration {
            version,
            debug_enabled,
            log_level,
            database_settings,
            feature_flags_enabled,
            max_connections,
            timeout_seconds,
        })
    }
}

impl ToFieldValue for Configuration {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }

examples/serialization/nested_structures.rs (line 77)

    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for ContactInfo {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize ContactInfo from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize ContactInfo from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for ContactInfo, found {}",
                value.type_name()
            ),
        })
    }
}

/// Address struct
#[derive(Debug, Clone, PartialEq)]
pub struct Address {
    pub street: String,
    pub city: String,
    pub state: String,
    pub postal_code: String,
    pub country: String,
}

impl StructSerializable for Address {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("street", &self.street)
            .field("city", &self.city)
            .field("state", &self.state)
            .field("postal_code", &self.postal_code)
            .field("country", &self.country)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let street = deserializer.field("street")?;
        let city = deserializer.field("city")?;
        let state = deserializer.field("state")?;
        let postal_code = deserializer.field("postal_code")?;
        let country = deserializer.field("country")?;

        Ok(Address {
            street,
            city,
            state,
            postal_code,
            country,
        })
    }
}

impl ToFieldValue for Address {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Address {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Address from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Address from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Address, found {}",
                value.type_name()
            ),
        })
    }
}

/// Project information struct
#[derive(Debug, Clone, PartialEq)]
pub struct Project {
    pub name: String,
    pub description: String,
    pub status: ProjectStatus,
    pub budget: f64,
    pub team_members: Vec<String>,
    pub milestones: Vec<Milestone>,
    pub metadata: HashMap<String, String>,
}

impl StructSerializable for Project {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("description", &self.description)
            .field("status", &self.status)
            .field("budget", &self.budget)
            .field("team_members", &self.team_members)
            .field("milestones", &self.milestones)
            .field("metadata", &self.metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let description = deserializer.field("description")?;
        let status = deserializer.field("status")?;
        let budget = deserializer.field("budget")?;
        let team_members = deserializer.field("team_members")?;
        let milestones = deserializer.field("milestones")?;
        let metadata = deserializer.field("metadata")?;

        Ok(Project {
            name,
            description,
            status,
            budget,
            team_members,
            milestones,
            metadata,
        })
    }
}

impl ToFieldValue for Project {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Project {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Project from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Project from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Project, found {}",
                value.type_name()
            ),
        })
    }
}

/// Project status enumeration
#[derive(Debug, Clone, PartialEq)]
pub enum ProjectStatus {
    Planning,
    InProgress,
    OnHold,
    Completed,
    Cancelled,
}

impl ToFieldValue for ProjectStatus {
    fn to_field_value(&self) -> FieldValue {
        let status_str = match self {
            ProjectStatus::Planning => "planning",
            ProjectStatus::InProgress => "in_progress",
            ProjectStatus::OnHold => "on_hold",
            ProjectStatus::Completed => "completed",
            ProjectStatus::Cancelled => "cancelled",
        };
        FieldValue::from_string(status_str.to_string())
    }
}

impl FromFieldValue for ProjectStatus {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        match value {
            FieldValue::String(s) => match s.as_str() {
                "planning" => Ok(ProjectStatus::Planning),
                "in_progress" => Ok(ProjectStatus::InProgress),
                "on_hold" => Ok(ProjectStatus::OnHold),
                "completed" => Ok(ProjectStatus::Completed),
                "cancelled" => Ok(ProjectStatus::Cancelled),
                _ => Err(SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Unknown project status: {}", s),
                }),
            },
            _ => Err(SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!(
                    "Expected String for ProjectStatus, found {}",
                    value.type_name()
                ),
            }),
        }
    }
}

/// Project milestone struct
#[derive(Debug, Clone, PartialEq)]
pub struct Milestone {
    pub name: String,
    pub description: String,
    pub due_date: String, // Simplified as string for this example
    pub is_completed: bool,
    pub progress_percentage: f32,
    pub dependencies: Vec<String>,
}

impl StructSerializable for Milestone {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("description", &self.description)
            .field("due_date", &self.due_date)
            .field("is_completed", &self.is_completed)
            .field("progress_percentage", &self.progress_percentage)
            .field("dependencies", &self.dependencies)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let description = deserializer.field("description")?;
        let due_date = deserializer.field("due_date")?;
        let is_completed = deserializer.field("is_completed")?;
        let progress_percentage = deserializer.field("progress_percentage")?;
        let dependencies = deserializer.field("dependencies")?;

        Ok(Milestone {
            name,
            description,
            due_date,
            is_completed,
            progress_percentage,
            dependencies,
        })
    }
}

impl ToFieldValue for Milestone {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Milestone {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Milestone from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Milestone from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Milestone, found {}",
                value.type_name()
            ),
        })
    }
}

/// Company struct with basic collections and nesting
#[derive(Debug, Clone, PartialEq)]
pub struct Company {
    pub name: String,
    pub founded_year: i32,
    pub headquarters_city: String,
    pub headquarters_state: String,
    pub employee_count: usize,
    pub department_names: Vec<String>,
    pub active_project_names: Vec<String>,
    pub company_metadata: HashMap<String, String>,
}

impl StructSerializable for Company {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("founded_year", &self.founded_year)
            .field("headquarters_city", &self.headquarters_city)
            .field("headquarters_state", &self.headquarters_state)
            .field("employee_count", &self.employee_count)
            .field("department_names", &self.department_names)
            .field("active_project_names", &self.active_project_names)
            .field("company_metadata", &self.company_metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let founded_year = deserializer.field("founded_year")?;
        let headquarters_city = deserializer.field("headquarters_city")?;
        let headquarters_state = deserializer.field("headquarters_state")?;
        let employee_count = deserializer.field("employee_count")?;
        let department_names = deserializer.field("department_names")?;
        let active_project_names = deserializer.field("active_project_names")?;
        let company_metadata = deserializer.field("company_metadata")?;

        Ok(Company {
            name,
            founded_year,
            headquarters_city,
            headquarters_state,
            employee_count,
            department_names,
            active_project_names,
            company_metadata,
        })
    }
}

impl ToFieldValue for Company {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Company {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Company from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Company from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Company, found {}",
                value.type_name()
            ),
        })
    }
}

/// Department struct
#[derive(Debug, Clone, PartialEq)]
pub struct Department {
    pub name: String,
    pub manager: String,
    pub employee_count: u32,
    pub budget: f64,
    pub office_locations: Vec<Address>,
}

impl StructSerializable for Department {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("manager", &self.manager)
            .field("employee_count", &self.employee_count)
            .field("budget", &self.budget)
            .field("office_locations", &self.office_locations)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let manager = deserializer.field("manager")?;
        let employee_count = deserializer.field("employee_count")?;
        let budget = deserializer.field("budget")?;
        let office_locations = deserializer.field("office_locations")?;

        Ok(Department {
            name,
            manager,
            employee_count,
            budget,
            office_locations,
        })
    }
}

impl ToFieldValue for Department {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }

examples/serialization/basic_structs.rs (line 85)

    fn to_field_value(&self) -> FieldValue {
        // Convert to JSON and then parse as FieldValue for nested object handling
        match self.to_json() {
            Ok(json_str) => {
                // For examples, we'll serialize as JSON string for simplicity
                FieldValue::from_json_object(json_str)
            }
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for UserProfile {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize UserProfile from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize UserProfile from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for UserProfile, found {}",
                value.type_name()
            ),
        })
    }
}

/// Application settings struct with optional fields and collections
#[derive(Debug, Clone, PartialEq)]
pub struct AppSettings {
    pub app_name: String,
    pub version: String,
    pub debug_mode: bool,
    pub max_connections: u32,
    pub timeout_seconds: f32,
    pub features: Vec<String>,
    pub environment_vars: HashMap<String, String>,
    pub optional_database_url: Option<String>,
}

impl StructSerializable for AppSettings {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("app_name", &self.app_name)
            .field("version", &self.version)
            .field("debug_mode", &self.debug_mode)
            .field("max_connections", &self.max_connections)
            .field("timeout_seconds", &self.timeout_seconds)
            .field("features", &self.features)
            .field("environment_vars", &self.environment_vars)
            .field("optional_database_url", &self.optional_database_url)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let app_name = deserializer.field("app_name")?;
        let version = deserializer.field("version")?;
        let debug_mode = deserializer.field("debug_mode")?;
        let max_connections = deserializer.field("max_connections")?;
        let timeout_seconds = deserializer.field("timeout_seconds")?;
        let features = deserializer.field("features")?;
        let environment_vars = deserializer.field("environment_vars")?;
        let optional_database_url = deserializer.field("optional_database_url")?;

        Ok(AppSettings {
            app_name,
            version,
            debug_mode,
            max_connections,
            timeout_seconds,
            features,
            environment_vars,
            optional_database_url,
        })
    }
}

impl ToFieldValue for AppSettings {
    fn to_field_value(&self) -> FieldValue {
        // Convert to JSON and then parse as FieldValue for nested object handling
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }

pub fn from_string_slice(value: &str) -> Self

Creates a string field value from a string slice

Arguments

• value - String slice to store (converted to owned string)

Returns

A FieldValue::String variant containing the string value

pub fn from_bytes(value: Vec<u8>) -> Self

Creates a byte array field value

Arguments

• value - Vector of bytes to store

Returns

A FieldValue::Bytes variant containing the byte array

pub fn from_json_object(json: String) -> Self

Creates a JSON object field value

Arguments

• json - JSON string representation of the object

Returns

A FieldValue::JsonObject variant containing the JSON string

Examples found in repository

examples/serialization/error_handling.rs (line 87)

    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for VersionedData {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize VersionedData from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize VersionedData from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for VersionedData, found {}",
                value.type_name()
            ),
        })
    }
}

/// Validated user input with constraints
#[derive(Debug, Clone, PartialEq)]
pub struct ValidatedUserInput {
    pub username: String,
    pub email: String,
    pub age: u16,
    pub preferences: HashMap<String, String>,
}

impl StructSerializable for ValidatedUserInput {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("username", &self.username)
            .field("email", &self.email)
            .field("age", &self.age)
            .field("preferences", &self.preferences)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let username: String = deserializer.field("username")?;
        let email: String = deserializer.field("email")?;
        let age: u16 = deserializer.field("age")?;
        let preferences: HashMap<String, String> = deserializer.field("preferences")?;

        // Validate username
        if username.is_empty() || username.len() > 50 {
            return Err(SerializationError::ValidationFailed {
                field: "username".to_string(),
                message: "Username must be 1-50 characters long".to_string(),
            });
        }

        if !username
            .chars()
            .all(|c| c.is_alphanumeric() || c == '_' || c == '-')
        {
            return Err(SerializationError::ValidationFailed {
                field: "username".to_string(),
                message:
                    "Username can only contain alphanumeric characters, underscores, and hyphens"
                        .to_string(),
            });
        }

        // Validate email (basic check)
        if !email.contains('@') || !email.contains('.') || email.len() < 5 {
            return Err(SerializationError::ValidationFailed {
                field: "email".to_string(),
                message: "Invalid email format".to_string(),
            });
        }

        // Validate age
        if !(13..=120).contains(&age) {
            return Err(SerializationError::ValidationFailed {
                field: "age".to_string(),
                message: "Age must be between 13 and 120".to_string(),
            });
        }

        // Validate preferences
        if preferences.len() > 20 {
            return Err(SerializationError::ValidationFailed {
                field: "preferences".to_string(),
                message: "Too many preferences (maximum 20)".to_string(),
            });
        }

        for (key, value) in &preferences {
            if key.len() > 50 || value.len() > 200 {
                return Err(SerializationError::ValidationFailed {
                    field: "preferences".to_string(),
                    message: format!("Preference key/value too long: {}", key),
                });
            }
        }

        Ok(ValidatedUserInput {
            username,
            email,
            age,
            preferences,
        })
    }
}

impl ToFieldValue for ValidatedUserInput {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for ValidatedUserInput {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize ValidatedUserInput from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!(
                        "Failed to deserialize ValidatedUserInput from binary: {}",
                        e
                    ),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for ValidatedUserInput, found {}",
                value.type_name()
            ),
        })
    }
}

/// Recovery helper for handling partial data
#[derive(Debug, Clone, PartialEq)]
pub struct RecoverableData {
    pub critical_field: String,
    pub important_field: Option<String>,
    pub optional_field: Option<String>,
    pub metadata: HashMap<String, String>,
}

impl StructSerializable for RecoverableData {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("critical_field", &self.critical_field)
            .field("important_field", &self.important_field)
            .field("optional_field", &self.optional_field)
            .field("metadata", &self.metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        // Critical field - must exist
        let critical_field = deserializer.field("critical_field")?;

        // Important field - try to recover if missing
        let important_field = deserializer.field_optional("important_field")?;

        // Optional field - graceful fallback
        let optional_field = deserializer.field_optional("optional_field")?;

        // Metadata - recover what we can
        let metadata = deserializer.field_or("metadata", HashMap::new())?;

        Ok(RecoverableData {
            critical_field,
            important_field,
            optional_field,
            metadata,
        })
    }
}

impl ToFieldValue for RecoverableData {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }

examples/serialization/json_vs_binary.rs (line 80)

    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for PerformanceMetrics {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize PerformanceMetrics from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!(
                        "Failed to deserialize PerformanceMetrics from binary: {}",
                        e
                    ),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for PerformanceMetrics, found {}",
                value.type_name()
            ),
        })
    }
}

/// Large dataset for performance testing
#[derive(Debug, Clone, PartialEq)]
pub struct LargeDataset {
    pub name: String,
    pub values: Vec<f32>, // Changed from f64 to f32 (supported)
    pub labels: Vec<String>,
    pub feature_count: usize, // Simplified from Vec<Vec<f32>> to just a count
    pub feature_dimension: usize, // Store dimensions separately
    pub metadata: HashMap<String, String>,
    pub timestamp_count: usize, // Simplified from Vec<u64> to just count
}

impl StructSerializable for LargeDataset {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("values", &self.values)
            .field("labels", &self.labels)
            .field("feature_count", &self.feature_count)
            .field("feature_dimension", &self.feature_dimension)
            .field("metadata", &self.metadata)
            .field("timestamp_count", &self.timestamp_count)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let values = deserializer.field("values")?;
        let labels = deserializer.field("labels")?;
        let feature_count = deserializer.field("feature_count")?;
        let feature_dimension = deserializer.field("feature_dimension")?;
        let metadata = deserializer.field("metadata")?;
        let timestamp_count = deserializer.field("timestamp_count")?;

        Ok(LargeDataset {
            name,
            values,
            labels,
            feature_count,
            feature_dimension,
            metadata,
            timestamp_count,
        })
    }
}

impl ToFieldValue for LargeDataset {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for LargeDataset {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize LargeDataset from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize LargeDataset from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for LargeDataset, found {}",
                value.type_name()
            ),
        })
    }
}

/// Configuration data (typical JSON use case)
#[derive(Debug, Clone, PartialEq)]
pub struct Configuration {
    pub version: String,
    pub debug_enabled: bool,
    pub log_level: String,
    pub database_settings: HashMap<String, String>,
    pub feature_flags_enabled: bool, // Simplified from HashMap<String, bool>
    pub max_connections: f32,        // Simplified from HashMap<String, f64>
    pub timeout_seconds: f32,
}

impl StructSerializable for Configuration {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("version", &self.version)
            .field("debug_enabled", &self.debug_enabled)
            .field("log_level", &self.log_level)
            .field("database_settings", &self.database_settings)
            .field("feature_flags_enabled", &self.feature_flags_enabled)
            .field("max_connections", &self.max_connections)
            .field("timeout_seconds", &self.timeout_seconds)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let version = deserializer.field("version")?;
        let debug_enabled = deserializer.field("debug_enabled")?;
        let log_level = deserializer.field("log_level")?;
        let database_settings = deserializer.field("database_settings")?;
        let feature_flags_enabled = deserializer.field("feature_flags_enabled")?;
        let max_connections = deserializer.field("max_connections")?;
        let timeout_seconds = deserializer.field("timeout_seconds")?;

        Ok(Configuration {
            version,
            debug_enabled,
            log_level,
            database_settings,
            feature_flags_enabled,
            max_connections,
            timeout_seconds,
        })
    }
}

impl ToFieldValue for Configuration {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }

examples/serialization/nested_structures.rs (line 76)

    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for ContactInfo {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize ContactInfo from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize ContactInfo from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for ContactInfo, found {}",
                value.type_name()
            ),
        })
    }
}

/// Address struct
#[derive(Debug, Clone, PartialEq)]
pub struct Address {
    pub street: String,
    pub city: String,
    pub state: String,
    pub postal_code: String,
    pub country: String,
}

impl StructSerializable for Address {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("street", &self.street)
            .field("city", &self.city)
            .field("state", &self.state)
            .field("postal_code", &self.postal_code)
            .field("country", &self.country)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let street = deserializer.field("street")?;
        let city = deserializer.field("city")?;
        let state = deserializer.field("state")?;
        let postal_code = deserializer.field("postal_code")?;
        let country = deserializer.field("country")?;

        Ok(Address {
            street,
            city,
            state,
            postal_code,
            country,
        })
    }
}

impl ToFieldValue for Address {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Address {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Address from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Address from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Address, found {}",
                value.type_name()
            ),
        })
    }
}

/// Project information struct
#[derive(Debug, Clone, PartialEq)]
pub struct Project {
    pub name: String,
    pub description: String,
    pub status: ProjectStatus,
    pub budget: f64,
    pub team_members: Vec<String>,
    pub milestones: Vec<Milestone>,
    pub metadata: HashMap<String, String>,
}

impl StructSerializable for Project {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("description", &self.description)
            .field("status", &self.status)
            .field("budget", &self.budget)
            .field("team_members", &self.team_members)
            .field("milestones", &self.milestones)
            .field("metadata", &self.metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let description = deserializer.field("description")?;
        let status = deserializer.field("status")?;
        let budget = deserializer.field("budget")?;
        let team_members = deserializer.field("team_members")?;
        let milestones = deserializer.field("milestones")?;
        let metadata = deserializer.field("metadata")?;

        Ok(Project {
            name,
            description,
            status,
            budget,
            team_members,
            milestones,
            metadata,
        })
    }
}

impl ToFieldValue for Project {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Project {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Project from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Project from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Project, found {}",
                value.type_name()
            ),
        })
    }
}

/// Project status enumeration
#[derive(Debug, Clone, PartialEq)]
pub enum ProjectStatus {
    Planning,
    InProgress,
    OnHold,
    Completed,
    Cancelled,
}

impl ToFieldValue for ProjectStatus {
    fn to_field_value(&self) -> FieldValue {
        let status_str = match self {
            ProjectStatus::Planning => "planning",
            ProjectStatus::InProgress => "in_progress",
            ProjectStatus::OnHold => "on_hold",
            ProjectStatus::Completed => "completed",
            ProjectStatus::Cancelled => "cancelled",
        };
        FieldValue::from_string(status_str.to_string())
    }
}

impl FromFieldValue for ProjectStatus {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        match value {
            FieldValue::String(s) => match s.as_str() {
                "planning" => Ok(ProjectStatus::Planning),
                "in_progress" => Ok(ProjectStatus::InProgress),
                "on_hold" => Ok(ProjectStatus::OnHold),
                "completed" => Ok(ProjectStatus::Completed),
                "cancelled" => Ok(ProjectStatus::Cancelled),
                _ => Err(SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Unknown project status: {}", s),
                }),
            },
            _ => Err(SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!(
                    "Expected String for ProjectStatus, found {}",
                    value.type_name()
                ),
            }),
        }
    }
}

/// Project milestone struct
#[derive(Debug, Clone, PartialEq)]
pub struct Milestone {
    pub name: String,
    pub description: String,
    pub due_date: String, // Simplified as string for this example
    pub is_completed: bool,
    pub progress_percentage: f32,
    pub dependencies: Vec<String>,
}

impl StructSerializable for Milestone {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("description", &self.description)
            .field("due_date", &self.due_date)
            .field("is_completed", &self.is_completed)
            .field("progress_percentage", &self.progress_percentage)
            .field("dependencies", &self.dependencies)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let description = deserializer.field("description")?;
        let due_date = deserializer.field("due_date")?;
        let is_completed = deserializer.field("is_completed")?;
        let progress_percentage = deserializer.field("progress_percentage")?;
        let dependencies = deserializer.field("dependencies")?;

        Ok(Milestone {
            name,
            description,
            due_date,
            is_completed,
            progress_percentage,
            dependencies,
        })
    }
}

impl ToFieldValue for Milestone {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Milestone {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Milestone from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Milestone from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Milestone, found {}",
                value.type_name()
            ),
        })
    }
}

/// Company struct with basic collections and nesting
#[derive(Debug, Clone, PartialEq)]
pub struct Company {
    pub name: String,
    pub founded_year: i32,
    pub headquarters_city: String,
    pub headquarters_state: String,
    pub employee_count: usize,
    pub department_names: Vec<String>,
    pub active_project_names: Vec<String>,
    pub company_metadata: HashMap<String, String>,
}

impl StructSerializable for Company {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("founded_year", &self.founded_year)
            .field("headquarters_city", &self.headquarters_city)
            .field("headquarters_state", &self.headquarters_state)
            .field("employee_count", &self.employee_count)
            .field("department_names", &self.department_names)
            .field("active_project_names", &self.active_project_names)
            .field("company_metadata", &self.company_metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let founded_year = deserializer.field("founded_year")?;
        let headquarters_city = deserializer.field("headquarters_city")?;
        let headquarters_state = deserializer.field("headquarters_state")?;
        let employee_count = deserializer.field("employee_count")?;
        let department_names = deserializer.field("department_names")?;
        let active_project_names = deserializer.field("active_project_names")?;
        let company_metadata = deserializer.field("company_metadata")?;

        Ok(Company {
            name,
            founded_year,
            headquarters_city,
            headquarters_state,
            employee_count,
            department_names,
            active_project_names,
            company_metadata,
        })
    }
}

impl ToFieldValue for Company {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Company {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Company from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Company from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Company, found {}",
                value.type_name()
            ),
        })
    }
}

/// Department struct
#[derive(Debug, Clone, PartialEq)]
pub struct Department {
    pub name: String,
    pub manager: String,
    pub employee_count: u32,
    pub budget: f64,
    pub office_locations: Vec<Address>,
}

impl StructSerializable for Department {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("manager", &self.manager)
            .field("employee_count", &self.employee_count)
            .field("budget", &self.budget)
            .field("office_locations", &self.office_locations)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let manager = deserializer.field("manager")?;
        let employee_count = deserializer.field("employee_count")?;
        let budget = deserializer.field("budget")?;
        let office_locations = deserializer.field("office_locations")?;

        Ok(Department {
            name,
            manager,
            employee_count,
            budget,
            office_locations,
        })
    }
}

impl ToFieldValue for Department {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }

examples/serialization/basic_structs.rs (line 83)

    fn to_field_value(&self) -> FieldValue {
        // Convert to JSON and then parse as FieldValue for nested object handling
        match self.to_json() {
            Ok(json_str) => {
                // For examples, we'll serialize as JSON string for simplicity
                FieldValue::from_json_object(json_str)
            }
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for UserProfile {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize UserProfile from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize UserProfile from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for UserProfile, found {}",
                value.type_name()
            ),
        })
    }
}

/// Application settings struct with optional fields and collections
#[derive(Debug, Clone, PartialEq)]
pub struct AppSettings {
    pub app_name: String,
    pub version: String,
    pub debug_mode: bool,
    pub max_connections: u32,
    pub timeout_seconds: f32,
    pub features: Vec<String>,
    pub environment_vars: HashMap<String, String>,
    pub optional_database_url: Option<String>,
}

impl StructSerializable for AppSettings {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("app_name", &self.app_name)
            .field("version", &self.version)
            .field("debug_mode", &self.debug_mode)
            .field("max_connections", &self.max_connections)
            .field("timeout_seconds", &self.timeout_seconds)
            .field("features", &self.features)
            .field("environment_vars", &self.environment_vars)
            .field("optional_database_url", &self.optional_database_url)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let app_name = deserializer.field("app_name")?;
        let version = deserializer.field("version")?;
        let debug_mode = deserializer.field("debug_mode")?;
        let max_connections = deserializer.field("max_connections")?;
        let timeout_seconds = deserializer.field("timeout_seconds")?;
        let features = deserializer.field("features")?;
        let environment_vars = deserializer.field("environment_vars")?;
        let optional_database_url = deserializer.field("optional_database_url")?;

        Ok(AppSettings {
            app_name,
            version,
            debug_mode,
            max_connections,
            timeout_seconds,
            features,
            environment_vars,
            optional_database_url,
        })
    }
}

impl ToFieldValue for AppSettings {
    fn to_field_value(&self) -> FieldValue {
        // Convert to JSON and then parse as FieldValue for nested object handling
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }

pub fn from_binary_object(data: Vec<u8>) -> Self

Creates a binary object field value

Arguments

• data - Binary data representing the serialized object

Returns

A FieldValue::BinaryObject variant containing the binary data

pub fn from_array(values: Vec<FieldValue>) -> Self

Creates an array field value

Arguments

• values - Vector of field values to store as an array

Returns

A FieldValue::Array variant containing the array of values

pub fn from_optional(value: Option<FieldValue>) -> Self

Creates an optional field value

Arguments

• value - Optional field value (None becomes Optional(None), Some(v) becomes Optional(Some(Box::new(v))))

Returns

A FieldValue::Optional variant containing the optional value

pub fn from_object(value: HashMap<String, FieldValue>) -> Self

Creates an object field value

Arguments

• value - HashMap of string keys to field values

Returns

A FieldValue::Object variant containing the key-value pairs

pub fn from_enum(variant: String, data: Option<FieldValue>) -> Self

Creates an enum field value with variant name and optional associated data

Arguments

• variant - Name of the enum variant
• data - Optional associated data for the variant

Returns

A FieldValue::Enum variant containing the variant name and optional data

pub fn from_enum_unit(variant: String) -> Self

Creates a unit enum variant with no associated data

Arguments

• variant - Name of the enum variant

Returns

A FieldValue::Enum variant with no associated data

pub fn from_enum_tuple(variant: String, values: Vec<FieldValue>) -> Self

Creates a tuple enum variant with array data

Arguments

• variant - Name of the enum variant
• values - Vector of field values representing the tuple data

Returns

A FieldValue::Enum variant with array data

pub fn from_enum_struct( variant: String, fields: HashMap<String, FieldValue>, ) -> Self

Creates a struct enum variant with object data

Arguments

• variant - Name of the enum variant
• fields - HashMap of field names to values representing the struct data

Returns

A FieldValue::Enum variant with object data

pub fn as_bool(&self) -> SerializationResult<bool>

Extracts a boolean value with type validation

Attempts to extract a boolean value from the field value. Returns an error if the field value is not a boolean type.

Returns

Ok(bool) if the field value is a boolean Err(SerializationError::ValidationFailed) if the field value is not a boolean

pub fn as_i8(&self) -> SerializationResult<i8>

Extracts an 8-bit signed integer value with type validation

Attempts to extract an 8-bit signed integer from the field value. Returns an error if the field value is not an i8 type.

Returns

Ok(i8) if the field value is an 8-bit signed integer Err(SerializationError::ValidationFailed) if the field value is not an i8

pub fn as_i16(&self) -> SerializationResult<i16>

Extracts a 16-bit signed integer value with type validation

Attempts to extract a 16-bit signed integer from the field value. Returns an error if the field value is not an i16 type.

Returns

Ok(i16) if the field value is a 16-bit signed integer Err(SerializationError::ValidationFailed) if the field value is not an i16

pub fn as_i32(&self) -> SerializationResult<i32>

Extracts a 32-bit signed integer value with type validation and conversion

Attempts to extract a 32-bit signed integer from the field value. Supports automatic conversion from smaller integer types (i8, i16) and validates range constraints for larger types (i64).

Returns

Ok(i32) if the field value can be converted to a 32-bit signed integer Err(SerializationError::ValidationFailed) if conversion fails or value is out of range

Conversion Rules

• i8, i16: Automatic conversion (always safe)
• i32: Direct extraction
• i64: Conversion with range validation (must be within i32::MIN..=i32::MAX)
• Other types: Conversion not supported

pub fn as_i64(&self) -> SerializationResult<i64>

Extracts a 64-bit signed integer value with type validation and conversion

Attempts to extract a 64-bit signed integer from the field value. Supports automatic conversion from smaller integer types (i8, i16, i32).

Returns

Ok(i64) if the field value can be converted to a 64-bit signed integer Err(SerializationError::ValidationFailed) if conversion is not supported

Conversion Rules

• i8, i16, i32: Automatic conversion (always safe)
• i64: Direct extraction
• Other types: Conversion not supported

pub fn as_u8(&self) -> SerializationResult<u8>

Extracts an 8-bit unsigned integer value with type validation

Attempts to extract an 8-bit unsigned integer from the field value. Returns an error if the field value is not a u8 type.

Returns

Ok(u8) if the field value is an 8-bit unsigned integer Err(SerializationError::ValidationFailed) if the field value is not a u8

pub fn as_u16(&self) -> SerializationResult<u16>

Extracts a 16-bit unsigned integer value with type validation

Attempts to extract a 16-bit unsigned integer from the field value. Returns an error if the field value is not a u16 type.

Returns

Ok(u16) if the field value is a 16-bit unsigned integer Err(SerializationError::ValidationFailed) if the field value is not a u16

pub fn as_u32(&self) -> SerializationResult<u32>

Extracts a 32-bit unsigned integer value with comprehensive type validation and conversion

Attempts to extract a 32-bit unsigned integer from the field value. Supports automatic conversion from compatible integer types with comprehensive range and sign validation.

Returns

Ok(u32) if the field value can be converted to a 32-bit unsigned integer Err(SerializationError::ValidationFailed) if conversion fails or value is out of range

Conversion Rules

Unsigned Types (Safe Conversions)

• u8, u16: Automatic conversion (always safe)
• u32: Direct extraction
• u64: Conversion with range validation (must be ≤ u32::MAX)
• usize: Conversion with range validation (must be ≤ u32::MAX)

Signed Types (Sign Validation Required)

• i8, i16, i32: Conversion only if value ≥ 0
• i64: Conversion only if value ≥ 0 and ≤ u32::MAX

Error Conditions

• Negative values from signed types
• Values exceeding u32::MAX from larger types
• Incompatible types (floats, strings, etc.)

pub fn as_u64(&self) -> SerializationResult<u64>

Extracts a 64-bit unsigned integer value with type validation and conversion

Attempts to extract a 64-bit unsigned integer from the field value. Supports automatic conversion from smaller unsigned types and signed types with sign validation.

Returns

Ok(u64) if the field value can be converted to a 64-bit unsigned integer Err(SerializationError::ValidationFailed) if conversion fails or value is negative

Conversion Rules

• u8, u16, u32, usize: Automatic conversion (always safe)
• u64: Direct extraction
• i8, i16, i32, i64: Conversion only if value ≥ 0
• Other types: Conversion not supported

pub fn as_usize(&self) -> SerializationResult<usize>

Extracts a platform-specific size integer value with type validation and conversion

Attempts to extract a platform-specific size integer from the field value. Supports automatic conversion from smaller unsigned types and signed types with sign validation.

Returns

Ok(usize) if the field value can be converted to a platform-specific size integer Err(SerializationError::ValidationFailed) if conversion fails or value is negative

Conversion Rules

• u8, u16, u32, u64: Automatic conversion (always safe)
• usize: Direct extraction
• i8, i16, i32, i64: Conversion only if value ≥ 0
• Other types: Conversion not supported

pub fn as_f32(&self) -> SerializationResult<f32>

Extracts a 32-bit floating point value with type validation and conversion

Attempts to extract a 32-bit floating point number from the field value. Supports automatic conversion from all numeric types with potential precision loss.

Returns

Ok(f32) if the field value can be converted to a 32-bit float Err(SerializationError::ValidationFailed) if conversion is not supported

Conversion Rules

• f32: Direct extraction
• f64: Conversion with potential precision loss
• All integer types: Automatic conversion (i8, i16, i32, i64, u8, u16, u32, u64, usize)
• Other types: Conversion not supported

pub fn as_f64(&self) -> SerializationResult<f64>

Extracts a 64-bit floating point value with type validation and conversion

Attempts to extract a 64-bit floating point number from the field value. Supports automatic conversion from all numeric types without precision loss.

Returns

Ok(f64) if the field value can be converted to a 64-bit float Err(SerializationError::ValidationFailed) if conversion is not supported

Conversion Rules

• f64: Direct extraction
• f32: Conversion without precision loss
• All integer types: Automatic conversion (i8, i16, i32, i64, u8, u16, u32, u64, usize)
• Other types: Conversion not supported

pub fn as_string(&self) -> SerializationResult<&str>

Extracts a string slice with type validation

Attempts to extract a string slice from the field value. Returns an error if the field value is not a string type.

Returns

Ok(&str) if the field value is a string Err(SerializationError::ValidationFailed) if the field value is not a string

pub fn as_bytes(&self) -> SerializationResult<&[u8]>

Extracts a byte slice with type validation

Attempts to extract a byte slice from the field value. Returns an error if the field value is not a byte array type.

Returns

Ok(&[u8]) if the field value is a byte array Err(SerializationError::ValidationFailed) if the field value is not a byte array

pub fn to_bytes(&self) -> SerializationResult<Vec<u8>>

Converts the field value to a byte vector with intelligent parsing

Attempts to convert the field value to a byte vector. For byte arrays, returns a clone of the data. For strings, attempts intelligent parsing including hex string conversion before falling back to UTF-8 encoding.

Returns

Ok(Vec<u8>) containing the byte data Err(SerializationError::ValidationFailed) if conversion fails

String Parsing Rules

The method attempts the following parsing strategies in order:

1. Hex string with 0x prefix: "0x1234abcd" → [0x12, 0x34, 0xab, 0xcd]
2. Plain hex string: "1234abcd" → [0x12, 0x34, 0xab, 0xcd]
3. UTF-8 encoding: Any other string → UTF-8 byte representation

Hex String Requirements

• Must contain only ASCII hex digits (0-9, a-f, A-F)
• Must have even length (pairs of hex digits)
• Optional “0x” prefix for explicit hex notation
• Empty strings are treated as UTF-8

Error Conditions

• Invalid hex characters in hex strings
• Odd-length hex strings
• Non-string/non-byte field values

pub fn as_json_object(&self) -> SerializationResult<&str>

Extracts a JSON object string with type validation

Attempts to extract a JSON object string from the field value. Returns an error if the field value is not a JSON object type.

Returns

Ok(&str) if the field value is a JSON object string Err(SerializationError::ValidationFailed) if the field value is not a JSON object

Examples found in repository

examples/serialization/basic_structs.rs (line 93)

    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize UserProfile from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize UserProfile from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for UserProfile, found {}",
                value.type_name()
            ),
        })
    }
}

/// Application settings struct with optional fields and collections
#[derive(Debug, Clone, PartialEq)]
pub struct AppSettings {
    pub app_name: String,
    pub version: String,
    pub debug_mode: bool,
    pub max_connections: u32,
    pub timeout_seconds: f32,
    pub features: Vec<String>,
    pub environment_vars: HashMap<String, String>,
    pub optional_database_url: Option<String>,
}

impl StructSerializable for AppSettings {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("app_name", &self.app_name)
            .field("version", &self.version)
            .field("debug_mode", &self.debug_mode)
            .field("max_connections", &self.max_connections)
            .field("timeout_seconds", &self.timeout_seconds)
            .field("features", &self.features)
            .field("environment_vars", &self.environment_vars)
            .field("optional_database_url", &self.optional_database_url)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let app_name = deserializer.field("app_name")?;
        let version = deserializer.field("version")?;
        let debug_mode = deserializer.field("debug_mode")?;
        let max_connections = deserializer.field("max_connections")?;
        let timeout_seconds = deserializer.field("timeout_seconds")?;
        let features = deserializer.field("features")?;
        let environment_vars = deserializer.field("environment_vars")?;
        let optional_database_url = deserializer.field("optional_database_url")?;

        Ok(AppSettings {
            app_name,
            version,
            debug_mode,
            max_connections,
            timeout_seconds,
            features,
            environment_vars,
            optional_database_url,
        })
    }
}

impl ToFieldValue for AppSettings {
    fn to_field_value(&self) -> FieldValue {
        // Convert to JSON and then parse as FieldValue for nested object handling
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for AppSettings {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize AppSettings from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize AppSettings from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for AppSettings, found {}",
                value.type_name()
            ),
        })
    }

examples/serialization/nested_structures.rs (line 85)

    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize ContactInfo from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize ContactInfo from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for ContactInfo, found {}",
                value.type_name()
            ),
        })
    }
}

/// Address struct
#[derive(Debug, Clone, PartialEq)]
pub struct Address {
    pub street: String,
    pub city: String,
    pub state: String,
    pub postal_code: String,
    pub country: String,
}

impl StructSerializable for Address {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("street", &self.street)
            .field("city", &self.city)
            .field("state", &self.state)
            .field("postal_code", &self.postal_code)
            .field("country", &self.country)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let street = deserializer.field("street")?;
        let city = deserializer.field("city")?;
        let state = deserializer.field("state")?;
        let postal_code = deserializer.field("postal_code")?;
        let country = deserializer.field("country")?;

        Ok(Address {
            street,
            city,
            state,
            postal_code,
            country,
        })
    }
}

impl ToFieldValue for Address {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Address {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Address from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Address from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Address, found {}",
                value.type_name()
            ),
        })
    }
}

/// Project information struct
#[derive(Debug, Clone, PartialEq)]
pub struct Project {
    pub name: String,
    pub description: String,
    pub status: ProjectStatus,
    pub budget: f64,
    pub team_members: Vec<String>,
    pub milestones: Vec<Milestone>,
    pub metadata: HashMap<String, String>,
}

impl StructSerializable for Project {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("description", &self.description)
            .field("status", &self.status)
            .field("budget", &self.budget)
            .field("team_members", &self.team_members)
            .field("milestones", &self.milestones)
            .field("metadata", &self.metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let description = deserializer.field("description")?;
        let status = deserializer.field("status")?;
        let budget = deserializer.field("budget")?;
        let team_members = deserializer.field("team_members")?;
        let milestones = deserializer.field("milestones")?;
        let metadata = deserializer.field("metadata")?;

        Ok(Project {
            name,
            description,
            status,
            budget,
            team_members,
            milestones,
            metadata,
        })
    }
}

impl ToFieldValue for Project {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Project {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Project from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Project from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Project, found {}",
                value.type_name()
            ),
        })
    }
}

/// Project status enumeration
#[derive(Debug, Clone, PartialEq)]
pub enum ProjectStatus {
    Planning,
    InProgress,
    OnHold,
    Completed,
    Cancelled,
}

impl ToFieldValue for ProjectStatus {
    fn to_field_value(&self) -> FieldValue {
        let status_str = match self {
            ProjectStatus::Planning => "planning",
            ProjectStatus::InProgress => "in_progress",
            ProjectStatus::OnHold => "on_hold",
            ProjectStatus::Completed => "completed",
            ProjectStatus::Cancelled => "cancelled",
        };
        FieldValue::from_string(status_str.to_string())
    }
}

impl FromFieldValue for ProjectStatus {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        match value {
            FieldValue::String(s) => match s.as_str() {
                "planning" => Ok(ProjectStatus::Planning),
                "in_progress" => Ok(ProjectStatus::InProgress),
                "on_hold" => Ok(ProjectStatus::OnHold),
                "completed" => Ok(ProjectStatus::Completed),
                "cancelled" => Ok(ProjectStatus::Cancelled),
                _ => Err(SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Unknown project status: {}", s),
                }),
            },
            _ => Err(SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!(
                    "Expected String for ProjectStatus, found {}",
                    value.type_name()
                ),
            }),
        }
    }
}

/// Project milestone struct
#[derive(Debug, Clone, PartialEq)]
pub struct Milestone {
    pub name: String,
    pub description: String,
    pub due_date: String, // Simplified as string for this example
    pub is_completed: bool,
    pub progress_percentage: f32,
    pub dependencies: Vec<String>,
}

impl StructSerializable for Milestone {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("description", &self.description)
            .field("due_date", &self.due_date)
            .field("is_completed", &self.is_completed)
            .field("progress_percentage", &self.progress_percentage)
            .field("dependencies", &self.dependencies)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let description = deserializer.field("description")?;
        let due_date = deserializer.field("due_date")?;
        let is_completed = deserializer.field("is_completed")?;
        let progress_percentage = deserializer.field("progress_percentage")?;
        let dependencies = deserializer.field("dependencies")?;

        Ok(Milestone {
            name,
            description,
            due_date,
            is_completed,
            progress_percentage,
            dependencies,
        })
    }
}

impl ToFieldValue for Milestone {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Milestone {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Milestone from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Milestone from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Milestone, found {}",
                value.type_name()
            ),
        })
    }
}

/// Company struct with basic collections and nesting
#[derive(Debug, Clone, PartialEq)]
pub struct Company {
    pub name: String,
    pub founded_year: i32,
    pub headquarters_city: String,
    pub headquarters_state: String,
    pub employee_count: usize,
    pub department_names: Vec<String>,
    pub active_project_names: Vec<String>,
    pub company_metadata: HashMap<String, String>,
}

impl StructSerializable for Company {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("founded_year", &self.founded_year)
            .field("headquarters_city", &self.headquarters_city)
            .field("headquarters_state", &self.headquarters_state)
            .field("employee_count", &self.employee_count)
            .field("department_names", &self.department_names)
            .field("active_project_names", &self.active_project_names)
            .field("company_metadata", &self.company_metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let founded_year = deserializer.field("founded_year")?;
        let headquarters_city = deserializer.field("headquarters_city")?;
        let headquarters_state = deserializer.field("headquarters_state")?;
        let employee_count = deserializer.field("employee_count")?;
        let department_names = deserializer.field("department_names")?;
        let active_project_names = deserializer.field("active_project_names")?;
        let company_metadata = deserializer.field("company_metadata")?;

        Ok(Company {
            name,
            founded_year,
            headquarters_city,
            headquarters_state,
            employee_count,
            department_names,
            active_project_names,
            company_metadata,
        })
    }
}

impl ToFieldValue for Company {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Company {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Company from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Company from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Company, found {}",
                value.type_name()
            ),
        })
    }
}

/// Department struct
#[derive(Debug, Clone, PartialEq)]
pub struct Department {
    pub name: String,
    pub manager: String,
    pub employee_count: u32,
    pub budget: f64,
    pub office_locations: Vec<Address>,
}

impl StructSerializable for Department {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("manager", &self.manager)
            .field("employee_count", &self.employee_count)
            .field("budget", &self.budget)
            .field("office_locations", &self.office_locations)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let manager = deserializer.field("manager")?;
        let employee_count = deserializer.field("employee_count")?;
        let budget = deserializer.field("budget")?;
        let office_locations = deserializer.field("office_locations")?;

        Ok(Department {
            name,
            manager,
            employee_count,
            budget,
            office_locations,
        })
    }
}

impl ToFieldValue for Department {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Department {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Department from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Department from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Department, found {}",
                value.type_name()
            ),
        })
    }

examples/serialization/error_handling.rs (line 96)

    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize VersionedData from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize VersionedData from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for VersionedData, found {}",
                value.type_name()
            ),
        })
    }
}

/// Validated user input with constraints
#[derive(Debug, Clone, PartialEq)]
pub struct ValidatedUserInput {
    pub username: String,
    pub email: String,
    pub age: u16,
    pub preferences: HashMap<String, String>,
}

impl StructSerializable for ValidatedUserInput {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("username", &self.username)
            .field("email", &self.email)
            .field("age", &self.age)
            .field("preferences", &self.preferences)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let username: String = deserializer.field("username")?;
        let email: String = deserializer.field("email")?;
        let age: u16 = deserializer.field("age")?;
        let preferences: HashMap<String, String> = deserializer.field("preferences")?;

        // Validate username
        if username.is_empty() || username.len() > 50 {
            return Err(SerializationError::ValidationFailed {
                field: "username".to_string(),
                message: "Username must be 1-50 characters long".to_string(),
            });
        }

        if !username
            .chars()
            .all(|c| c.is_alphanumeric() || c == '_' || c == '-')
        {
            return Err(SerializationError::ValidationFailed {
                field: "username".to_string(),
                message:
                    "Username can only contain alphanumeric characters, underscores, and hyphens"
                        .to_string(),
            });
        }

        // Validate email (basic check)
        if !email.contains('@') || !email.contains('.') || email.len() < 5 {
            return Err(SerializationError::ValidationFailed {
                field: "email".to_string(),
                message: "Invalid email format".to_string(),
            });
        }

        // Validate age
        if !(13..=120).contains(&age) {
            return Err(SerializationError::ValidationFailed {
                field: "age".to_string(),
                message: "Age must be between 13 and 120".to_string(),
            });
        }

        // Validate preferences
        if preferences.len() > 20 {
            return Err(SerializationError::ValidationFailed {
                field: "preferences".to_string(),
                message: "Too many preferences (maximum 20)".to_string(),
            });
        }

        for (key, value) in &preferences {
            if key.len() > 50 || value.len() > 200 {
                return Err(SerializationError::ValidationFailed {
                    field: "preferences".to_string(),
                    message: format!("Preference key/value too long: {}", key),
                });
            }
        }

        Ok(ValidatedUserInput {
            username,
            email,
            age,
            preferences,
        })
    }
}

impl ToFieldValue for ValidatedUserInput {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for ValidatedUserInput {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize ValidatedUserInput from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!(
                        "Failed to deserialize ValidatedUserInput from binary: {}",
                        e
                    ),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for ValidatedUserInput, found {}",
                value.type_name()
            ),
        })
    }
}

/// Recovery helper for handling partial data
#[derive(Debug, Clone, PartialEq)]
pub struct RecoverableData {
    pub critical_field: String,
    pub important_field: Option<String>,
    pub optional_field: Option<String>,
    pub metadata: HashMap<String, String>,
}

impl StructSerializable for RecoverableData {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("critical_field", &self.critical_field)
            .field("important_field", &self.important_field)
            .field("optional_field", &self.optional_field)
            .field("metadata", &self.metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        // Critical field - must exist
        let critical_field = deserializer.field("critical_field")?;

        // Important field - try to recover if missing
        let important_field = deserializer.field_optional("important_field")?;

        // Optional field - graceful fallback
        let optional_field = deserializer.field_optional("optional_field")?;

        // Metadata - recover what we can
        let metadata = deserializer.field_or("metadata", HashMap::new())?;

        Ok(RecoverableData {
            critical_field,
            important_field,
            optional_field,
            metadata,
        })
    }
}

impl ToFieldValue for RecoverableData {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for RecoverableData {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize RecoverableData from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize RecoverableData from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for RecoverableData, found {}",
                value.type_name()
            ),
        })
    }

examples/serialization/json_vs_binary.rs (line 89)

    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize PerformanceMetrics from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!(
                        "Failed to deserialize PerformanceMetrics from binary: {}",
                        e
                    ),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for PerformanceMetrics, found {}",
                value.type_name()
            ),
        })
    }
}

/// Large dataset for performance testing
#[derive(Debug, Clone, PartialEq)]
pub struct LargeDataset {
    pub name: String,
    pub values: Vec<f32>, // Changed from f64 to f32 (supported)
    pub labels: Vec<String>,
    pub feature_count: usize, // Simplified from Vec<Vec<f32>> to just a count
    pub feature_dimension: usize, // Store dimensions separately
    pub metadata: HashMap<String, String>,
    pub timestamp_count: usize, // Simplified from Vec<u64> to just count
}

impl StructSerializable for LargeDataset {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("values", &self.values)
            .field("labels", &self.labels)
            .field("feature_count", &self.feature_count)
            .field("feature_dimension", &self.feature_dimension)
            .field("metadata", &self.metadata)
            .field("timestamp_count", &self.timestamp_count)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let values = deserializer.field("values")?;
        let labels = deserializer.field("labels")?;
        let feature_count = deserializer.field("feature_count")?;
        let feature_dimension = deserializer.field("feature_dimension")?;
        let metadata = deserializer.field("metadata")?;
        let timestamp_count = deserializer.field("timestamp_count")?;

        Ok(LargeDataset {
            name,
            values,
            labels,
            feature_count,
            feature_dimension,
            metadata,
            timestamp_count,
        })
    }
}

impl ToFieldValue for LargeDataset {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for LargeDataset {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize LargeDataset from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize LargeDataset from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for LargeDataset, found {}",
                value.type_name()
            ),
        })
    }
}

/// Configuration data (typical JSON use case)
#[derive(Debug, Clone, PartialEq)]
pub struct Configuration {
    pub version: String,
    pub debug_enabled: bool,
    pub log_level: String,
    pub database_settings: HashMap<String, String>,
    pub feature_flags_enabled: bool, // Simplified from HashMap<String, bool>
    pub max_connections: f32,        // Simplified from HashMap<String, f64>
    pub timeout_seconds: f32,
}

impl StructSerializable for Configuration {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("version", &self.version)
            .field("debug_enabled", &self.debug_enabled)
            .field("log_level", &self.log_level)
            .field("database_settings", &self.database_settings)
            .field("feature_flags_enabled", &self.feature_flags_enabled)
            .field("max_connections", &self.max_connections)
            .field("timeout_seconds", &self.timeout_seconds)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let version = deserializer.field("version")?;
        let debug_enabled = deserializer.field("debug_enabled")?;
        let log_level = deserializer.field("log_level")?;
        let database_settings = deserializer.field("database_settings")?;
        let feature_flags_enabled = deserializer.field("feature_flags_enabled")?;
        let max_connections = deserializer.field("max_connections")?;
        let timeout_seconds = deserializer.field("timeout_seconds")?;

        Ok(Configuration {
            version,
            debug_enabled,
            log_level,
            database_settings,
            feature_flags_enabled,
            max_connections,
            timeout_seconds,
        })
    }
}

impl ToFieldValue for Configuration {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Configuration {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Configuration from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Configuration from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Configuration, found {}",
                value.type_name()
            ),
        })
    }

pub fn as_binary_object(&self) -> SerializationResult<&[u8]>

Extracts binary object data with type validation

Attempts to extract binary object data from the field value. Returns an error if the field value is not a binary object type.

Returns

Ok(&[u8]) if the field value is binary object data Err(SerializationError::ValidationFailed) if the field value is not a binary object

Examples found in repository

examples/serialization/basic_structs.rs (line 101)

    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize UserProfile from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize UserProfile from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for UserProfile, found {}",
                value.type_name()
            ),
        })
    }
}

/// Application settings struct with optional fields and collections
#[derive(Debug, Clone, PartialEq)]
pub struct AppSettings {
    pub app_name: String,
    pub version: String,
    pub debug_mode: bool,
    pub max_connections: u32,
    pub timeout_seconds: f32,
    pub features: Vec<String>,
    pub environment_vars: HashMap<String, String>,
    pub optional_database_url: Option<String>,
}

impl StructSerializable for AppSettings {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("app_name", &self.app_name)
            .field("version", &self.version)
            .field("debug_mode", &self.debug_mode)
            .field("max_connections", &self.max_connections)
            .field("timeout_seconds", &self.timeout_seconds)
            .field("features", &self.features)
            .field("environment_vars", &self.environment_vars)
            .field("optional_database_url", &self.optional_database_url)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let app_name = deserializer.field("app_name")?;
        let version = deserializer.field("version")?;
        let debug_mode = deserializer.field("debug_mode")?;
        let max_connections = deserializer.field("max_connections")?;
        let timeout_seconds = deserializer.field("timeout_seconds")?;
        let features = deserializer.field("features")?;
        let environment_vars = deserializer.field("environment_vars")?;
        let optional_database_url = deserializer.field("optional_database_url")?;

        Ok(AppSettings {
            app_name,
            version,
            debug_mode,
            max_connections,
            timeout_seconds,
            features,
            environment_vars,
            optional_database_url,
        })
    }
}

impl ToFieldValue for AppSettings {
    fn to_field_value(&self) -> FieldValue {
        // Convert to JSON and then parse as FieldValue for nested object handling
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for AppSettings {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize AppSettings from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize AppSettings from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for AppSettings, found {}",
                value.type_name()
            ),
        })
    }

examples/serialization/nested_structures.rs (line 93)

    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize ContactInfo from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize ContactInfo from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for ContactInfo, found {}",
                value.type_name()
            ),
        })
    }
}

/// Address struct
#[derive(Debug, Clone, PartialEq)]
pub struct Address {
    pub street: String,
    pub city: String,
    pub state: String,
    pub postal_code: String,
    pub country: String,
}

impl StructSerializable for Address {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("street", &self.street)
            .field("city", &self.city)
            .field("state", &self.state)
            .field("postal_code", &self.postal_code)
            .field("country", &self.country)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let street = deserializer.field("street")?;
        let city = deserializer.field("city")?;
        let state = deserializer.field("state")?;
        let postal_code = deserializer.field("postal_code")?;
        let country = deserializer.field("country")?;

        Ok(Address {
            street,
            city,
            state,
            postal_code,
            country,
        })
    }
}

impl ToFieldValue for Address {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Address {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Address from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Address from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Address, found {}",
                value.type_name()
            ),
        })
    }
}

/// Project information struct
#[derive(Debug, Clone, PartialEq)]
pub struct Project {
    pub name: String,
    pub description: String,
    pub status: ProjectStatus,
    pub budget: f64,
    pub team_members: Vec<String>,
    pub milestones: Vec<Milestone>,
    pub metadata: HashMap<String, String>,
}

impl StructSerializable for Project {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("description", &self.description)
            .field("status", &self.status)
            .field("budget", &self.budget)
            .field("team_members", &self.team_members)
            .field("milestones", &self.milestones)
            .field("metadata", &self.metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let description = deserializer.field("description")?;
        let status = deserializer.field("status")?;
        let budget = deserializer.field("budget")?;
        let team_members = deserializer.field("team_members")?;
        let milestones = deserializer.field("milestones")?;
        let metadata = deserializer.field("metadata")?;

        Ok(Project {
            name,
            description,
            status,
            budget,
            team_members,
            milestones,
            metadata,
        })
    }
}

impl ToFieldValue for Project {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Project {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Project from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Project from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Project, found {}",
                value.type_name()
            ),
        })
    }
}

/// Project status enumeration
#[derive(Debug, Clone, PartialEq)]
pub enum ProjectStatus {
    Planning,
    InProgress,
    OnHold,
    Completed,
    Cancelled,
}

impl ToFieldValue for ProjectStatus {
    fn to_field_value(&self) -> FieldValue {
        let status_str = match self {
            ProjectStatus::Planning => "planning",
            ProjectStatus::InProgress => "in_progress",
            ProjectStatus::OnHold => "on_hold",
            ProjectStatus::Completed => "completed",
            ProjectStatus::Cancelled => "cancelled",
        };
        FieldValue::from_string(status_str.to_string())
    }
}

impl FromFieldValue for ProjectStatus {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        match value {
            FieldValue::String(s) => match s.as_str() {
                "planning" => Ok(ProjectStatus::Planning),
                "in_progress" => Ok(ProjectStatus::InProgress),
                "on_hold" => Ok(ProjectStatus::OnHold),
                "completed" => Ok(ProjectStatus::Completed),
                "cancelled" => Ok(ProjectStatus::Cancelled),
                _ => Err(SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Unknown project status: {}", s),
                }),
            },
            _ => Err(SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!(
                    "Expected String for ProjectStatus, found {}",
                    value.type_name()
                ),
            }),
        }
    }
}

/// Project milestone struct
#[derive(Debug, Clone, PartialEq)]
pub struct Milestone {
    pub name: String,
    pub description: String,
    pub due_date: String, // Simplified as string for this example
    pub is_completed: bool,
    pub progress_percentage: f32,
    pub dependencies: Vec<String>,
}

impl StructSerializable for Milestone {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("description", &self.description)
            .field("due_date", &self.due_date)
            .field("is_completed", &self.is_completed)
            .field("progress_percentage", &self.progress_percentage)
            .field("dependencies", &self.dependencies)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let description = deserializer.field("description")?;
        let due_date = deserializer.field("due_date")?;
        let is_completed = deserializer.field("is_completed")?;
        let progress_percentage = deserializer.field("progress_percentage")?;
        let dependencies = deserializer.field("dependencies")?;

        Ok(Milestone {
            name,
            description,
            due_date,
            is_completed,
            progress_percentage,
            dependencies,
        })
    }
}

impl ToFieldValue for Milestone {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Milestone {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Milestone from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Milestone from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Milestone, found {}",
                value.type_name()
            ),
        })
    }
}

/// Company struct with basic collections and nesting
#[derive(Debug, Clone, PartialEq)]
pub struct Company {
    pub name: String,
    pub founded_year: i32,
    pub headquarters_city: String,
    pub headquarters_state: String,
    pub employee_count: usize,
    pub department_names: Vec<String>,
    pub active_project_names: Vec<String>,
    pub company_metadata: HashMap<String, String>,
}

impl StructSerializable for Company {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("founded_year", &self.founded_year)
            .field("headquarters_city", &self.headquarters_city)
            .field("headquarters_state", &self.headquarters_state)
            .field("employee_count", &self.employee_count)
            .field("department_names", &self.department_names)
            .field("active_project_names", &self.active_project_names)
            .field("company_metadata", &self.company_metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let founded_year = deserializer.field("founded_year")?;
        let headquarters_city = deserializer.field("headquarters_city")?;
        let headquarters_state = deserializer.field("headquarters_state")?;
        let employee_count = deserializer.field("employee_count")?;
        let department_names = deserializer.field("department_names")?;
        let active_project_names = deserializer.field("active_project_names")?;
        let company_metadata = deserializer.field("company_metadata")?;

        Ok(Company {
            name,
            founded_year,
            headquarters_city,
            headquarters_state,
            employee_count,
            department_names,
            active_project_names,
            company_metadata,
        })
    }
}

impl ToFieldValue for Company {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Company {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Company from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Company from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Company, found {}",
                value.type_name()
            ),
        })
    }
}

/// Department struct
#[derive(Debug, Clone, PartialEq)]
pub struct Department {
    pub name: String,
    pub manager: String,
    pub employee_count: u32,
    pub budget: f64,
    pub office_locations: Vec<Address>,
}

impl StructSerializable for Department {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("manager", &self.manager)
            .field("employee_count", &self.employee_count)
            .field("budget", &self.budget)
            .field("office_locations", &self.office_locations)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let manager = deserializer.field("manager")?;
        let employee_count = deserializer.field("employee_count")?;
        let budget = deserializer.field("budget")?;
        let office_locations = deserializer.field("office_locations")?;

        Ok(Department {
            name,
            manager,
            employee_count,
            budget,
            office_locations,
        })
    }
}

impl ToFieldValue for Department {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Department {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Department from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Department from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Department, found {}",
                value.type_name()
            ),
        })
    }

examples/serialization/error_handling.rs (line 104)

    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize VersionedData from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize VersionedData from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for VersionedData, found {}",
                value.type_name()
            ),
        })
    }
}

/// Validated user input with constraints
#[derive(Debug, Clone, PartialEq)]
pub struct ValidatedUserInput {
    pub username: String,
    pub email: String,
    pub age: u16,
    pub preferences: HashMap<String, String>,
}

impl StructSerializable for ValidatedUserInput {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("username", &self.username)
            .field("email", &self.email)
            .field("age", &self.age)
            .field("preferences", &self.preferences)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let username: String = deserializer.field("username")?;
        let email: String = deserializer.field("email")?;
        let age: u16 = deserializer.field("age")?;
        let preferences: HashMap<String, String> = deserializer.field("preferences")?;

        // Validate username
        if username.is_empty() || username.len() > 50 {
            return Err(SerializationError::ValidationFailed {
                field: "username".to_string(),
                message: "Username must be 1-50 characters long".to_string(),
            });
        }

        if !username
            .chars()
            .all(|c| c.is_alphanumeric() || c == '_' || c == '-')
        {
            return Err(SerializationError::ValidationFailed {
                field: "username".to_string(),
                message:
                    "Username can only contain alphanumeric characters, underscores, and hyphens"
                        .to_string(),
            });
        }

        // Validate email (basic check)
        if !email.contains('@') || !email.contains('.') || email.len() < 5 {
            return Err(SerializationError::ValidationFailed {
                field: "email".to_string(),
                message: "Invalid email format".to_string(),
            });
        }

        // Validate age
        if !(13..=120).contains(&age) {
            return Err(SerializationError::ValidationFailed {
                field: "age".to_string(),
                message: "Age must be between 13 and 120".to_string(),
            });
        }

        // Validate preferences
        if preferences.len() > 20 {
            return Err(SerializationError::ValidationFailed {
                field: "preferences".to_string(),
                message: "Too many preferences (maximum 20)".to_string(),
            });
        }

        for (key, value) in &preferences {
            if key.len() > 50 || value.len() > 200 {
                return Err(SerializationError::ValidationFailed {
                    field: "preferences".to_string(),
                    message: format!("Preference key/value too long: {}", key),
                });
            }
        }

        Ok(ValidatedUserInput {
            username,
            email,
            age,
            preferences,
        })
    }
}

impl ToFieldValue for ValidatedUserInput {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for ValidatedUserInput {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize ValidatedUserInput from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!(
                        "Failed to deserialize ValidatedUserInput from binary: {}",
                        e
                    ),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for ValidatedUserInput, found {}",
                value.type_name()
            ),
        })
    }
}

/// Recovery helper for handling partial data
#[derive(Debug, Clone, PartialEq)]
pub struct RecoverableData {
    pub critical_field: String,
    pub important_field: Option<String>,
    pub optional_field: Option<String>,
    pub metadata: HashMap<String, String>,
}

impl StructSerializable for RecoverableData {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("critical_field", &self.critical_field)
            .field("important_field", &self.important_field)
            .field("optional_field", &self.optional_field)
            .field("metadata", &self.metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        // Critical field - must exist
        let critical_field = deserializer.field("critical_field")?;

        // Important field - try to recover if missing
        let important_field = deserializer.field_optional("important_field")?;

        // Optional field - graceful fallback
        let optional_field = deserializer.field_optional("optional_field")?;

        // Metadata - recover what we can
        let metadata = deserializer.field_or("metadata", HashMap::new())?;

        Ok(RecoverableData {
            critical_field,
            important_field,
            optional_field,
            metadata,
        })
    }
}

impl ToFieldValue for RecoverableData {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for RecoverableData {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize RecoverableData from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize RecoverableData from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for RecoverableData, found {}",
                value.type_name()
            ),
        })
    }

examples/serialization/json_vs_binary.rs (line 97)

    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize PerformanceMetrics from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!(
                        "Failed to deserialize PerformanceMetrics from binary: {}",
                        e
                    ),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for PerformanceMetrics, found {}",
                value.type_name()
            ),
        })
    }
}

/// Large dataset for performance testing
#[derive(Debug, Clone, PartialEq)]
pub struct LargeDataset {
    pub name: String,
    pub values: Vec<f32>, // Changed from f64 to f32 (supported)
    pub labels: Vec<String>,
    pub feature_count: usize, // Simplified from Vec<Vec<f32>> to just a count
    pub feature_dimension: usize, // Store dimensions separately
    pub metadata: HashMap<String, String>,
    pub timestamp_count: usize, // Simplified from Vec<u64> to just count
}

impl StructSerializable for LargeDataset {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("values", &self.values)
            .field("labels", &self.labels)
            .field("feature_count", &self.feature_count)
            .field("feature_dimension", &self.feature_dimension)
            .field("metadata", &self.metadata)
            .field("timestamp_count", &self.timestamp_count)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let values = deserializer.field("values")?;
        let labels = deserializer.field("labels")?;
        let feature_count = deserializer.field("feature_count")?;
        let feature_dimension = deserializer.field("feature_dimension")?;
        let metadata = deserializer.field("metadata")?;
        let timestamp_count = deserializer.field("timestamp_count")?;

        Ok(LargeDataset {
            name,
            values,
            labels,
            feature_count,
            feature_dimension,
            metadata,
            timestamp_count,
        })
    }
}

impl ToFieldValue for LargeDataset {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for LargeDataset {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize LargeDataset from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize LargeDataset from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for LargeDataset, found {}",
                value.type_name()
            ),
        })
    }
}

/// Configuration data (typical JSON use case)
#[derive(Debug, Clone, PartialEq)]
pub struct Configuration {
    pub version: String,
    pub debug_enabled: bool,
    pub log_level: String,
    pub database_settings: HashMap<String, String>,
    pub feature_flags_enabled: bool, // Simplified from HashMap<String, bool>
    pub max_connections: f32,        // Simplified from HashMap<String, f64>
    pub timeout_seconds: f32,
}

impl StructSerializable for Configuration {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("version", &self.version)
            .field("debug_enabled", &self.debug_enabled)
            .field("log_level", &self.log_level)
            .field("database_settings", &self.database_settings)
            .field("feature_flags_enabled", &self.feature_flags_enabled)
            .field("max_connections", &self.max_connections)
            .field("timeout_seconds", &self.timeout_seconds)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let version = deserializer.field("version")?;
        let debug_enabled = deserializer.field("debug_enabled")?;
        let log_level = deserializer.field("log_level")?;
        let database_settings = deserializer.field("database_settings")?;
        let feature_flags_enabled = deserializer.field("feature_flags_enabled")?;
        let max_connections = deserializer.field("max_connections")?;
        let timeout_seconds = deserializer.field("timeout_seconds")?;

        Ok(Configuration {
            version,
            debug_enabled,
            log_level,
            database_settings,
            feature_flags_enabled,
            max_connections,
            timeout_seconds,
        })
    }
}

impl ToFieldValue for Configuration {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Configuration {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Configuration from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Configuration from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Configuration, found {}",
                value.type_name()
            ),
        })
    }

pub fn as_array(&self) -> SerializationResult<&[FieldValue]>

Extracts an array of field values with type validation

Attempts to extract an array of field values from the field value. Returns an error if the field value is not an array type.

Returns

Ok(&[FieldValue]) if the field value is an array Err(SerializationError::ValidationFailed) if the field value is not an array

pub fn as_optional(&self) -> SerializationResult<Option<&FieldValue>>

Extracts an optional field value with type validation

Attempts to extract an optional field value from the field value. Returns an error if the field value is not an optional type.

Returns

Ok(Option<&FieldValue>) if the field value is an optional Err(SerializationError::ValidationFailed) if the field value is not an optional

pub fn as_object(&self) -> SerializationResult<&HashMap<String, FieldValue>>

Extracts an object map with type validation

Attempts to extract a key-value object map from the field value. Returns an error if the field value is not an object type.

Returns

Ok(&HashMap<String, FieldValue>) if the field value is an object Err(SerializationError::ValidationFailed) if the field value is not an object

pub fn as_enum(&self) -> SerializationResult<(&str, Option<&FieldValue>)>

Extracts enum variant name and associated data with type validation

Attempts to extract both the enum variant name and its associated data from the field value. Returns an error if the field value is not an enum type.

Returns

Ok((&str, Option<&FieldValue>)) containing the variant name and optional data Err(SerializationError::ValidationFailed) if the field value is not an enum

pub fn as_enum_variant(&self) -> SerializationResult<&str>

Extracts enum variant name with type validation

Attempts to extract the enum variant name from the field value. Returns an error if the field value is not an enum type.

Returns

Ok(&str) containing the enum variant name Err(SerializationError::ValidationFailed) if the field value is not an enum

pub fn as_enum_data(&self) -> SerializationResult<Option<&FieldValue>>

Extracts enum associated data with type validation

Attempts to extract the associated data from the enum field value. Returns an error if the field value is not an enum type.

Returns

Ok(Option<&FieldValue>) containing the optional associated data Err(SerializationError::ValidationFailed) if the field value is not an enum

pub fn type_name(&self) -> &'static str

Returns the human-readable type name for error reporting

Provides a consistent string representation of the field value type for use in error messages and debugging. The returned string is static and does not depend on the actual value content.

Returns

A static string slice representing the type name

Type Names

• Primitive types: "bool", "i8", "i16", "i32", "i64", "u8", "u16", "u32", "u64", "usize", "f32", "f64"
• String types: "string"
• Binary types: "bytes"
• Object types: "json_object", "binary_object"
• Collection types: "array", "optional", "object"
• Enum types: "enum"

Examples found in repository

examples/serialization/basic_structs.rs (line 114)

    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize UserProfile from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize UserProfile from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for UserProfile, found {}",
                value.type_name()
            ),
        })
    }
}

/// Application settings struct with optional fields and collections
#[derive(Debug, Clone, PartialEq)]
pub struct AppSettings {
    pub app_name: String,
    pub version: String,
    pub debug_mode: bool,
    pub max_connections: u32,
    pub timeout_seconds: f32,
    pub features: Vec<String>,
    pub environment_vars: HashMap<String, String>,
    pub optional_database_url: Option<String>,
}

impl StructSerializable for AppSettings {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("app_name", &self.app_name)
            .field("version", &self.version)
            .field("debug_mode", &self.debug_mode)
            .field("max_connections", &self.max_connections)
            .field("timeout_seconds", &self.timeout_seconds)
            .field("features", &self.features)
            .field("environment_vars", &self.environment_vars)
            .field("optional_database_url", &self.optional_database_url)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let app_name = deserializer.field("app_name")?;
        let version = deserializer.field("version")?;
        let debug_mode = deserializer.field("debug_mode")?;
        let max_connections = deserializer.field("max_connections")?;
        let timeout_seconds = deserializer.field("timeout_seconds")?;
        let features = deserializer.field("features")?;
        let environment_vars = deserializer.field("environment_vars")?;
        let optional_database_url = deserializer.field("optional_database_url")?;

        Ok(AppSettings {
            app_name,
            version,
            debug_mode,
            max_connections,
            timeout_seconds,
            features,
            environment_vars,
            optional_database_url,
        })
    }
}

impl ToFieldValue for AppSettings {
    fn to_field_value(&self) -> FieldValue {
        // Convert to JSON and then parse as FieldValue for nested object handling
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for AppSettings {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize AppSettings from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize AppSettings from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for AppSettings, found {}",
                value.type_name()
            ),
        })
    }

examples/serialization/nested_structures.rs (line 106)

    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize ContactInfo from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize ContactInfo from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for ContactInfo, found {}",
                value.type_name()
            ),
        })
    }
}

/// Address struct
#[derive(Debug, Clone, PartialEq)]
pub struct Address {
    pub street: String,
    pub city: String,
    pub state: String,
    pub postal_code: String,
    pub country: String,
}

impl StructSerializable for Address {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("street", &self.street)
            .field("city", &self.city)
            .field("state", &self.state)
            .field("postal_code", &self.postal_code)
            .field("country", &self.country)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let street = deserializer.field("street")?;
        let city = deserializer.field("city")?;
        let state = deserializer.field("state")?;
        let postal_code = deserializer.field("postal_code")?;
        let country = deserializer.field("country")?;

        Ok(Address {
            street,
            city,
            state,
            postal_code,
            country,
        })
    }
}

impl ToFieldValue for Address {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Address {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Address from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Address from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Address, found {}",
                value.type_name()
            ),
        })
    }
}

/// Project information struct
#[derive(Debug, Clone, PartialEq)]
pub struct Project {
    pub name: String,
    pub description: String,
    pub status: ProjectStatus,
    pub budget: f64,
    pub team_members: Vec<String>,
    pub milestones: Vec<Milestone>,
    pub metadata: HashMap<String, String>,
}

impl StructSerializable for Project {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("description", &self.description)
            .field("status", &self.status)
            .field("budget", &self.budget)
            .field("team_members", &self.team_members)
            .field("milestones", &self.milestones)
            .field("metadata", &self.metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let description = deserializer.field("description")?;
        let status = deserializer.field("status")?;
        let budget = deserializer.field("budget")?;
        let team_members = deserializer.field("team_members")?;
        let milestones = deserializer.field("milestones")?;
        let metadata = deserializer.field("metadata")?;

        Ok(Project {
            name,
            description,
            status,
            budget,
            team_members,
            milestones,
            metadata,
        })
    }
}

impl ToFieldValue for Project {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Project {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Project from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Project from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Project, found {}",
                value.type_name()
            ),
        })
    }
}

/// Project status enumeration
#[derive(Debug, Clone, PartialEq)]
pub enum ProjectStatus {
    Planning,
    InProgress,
    OnHold,
    Completed,
    Cancelled,
}

impl ToFieldValue for ProjectStatus {
    fn to_field_value(&self) -> FieldValue {
        let status_str = match self {
            ProjectStatus::Planning => "planning",
            ProjectStatus::InProgress => "in_progress",
            ProjectStatus::OnHold => "on_hold",
            ProjectStatus::Completed => "completed",
            ProjectStatus::Cancelled => "cancelled",
        };
        FieldValue::from_string(status_str.to_string())
    }
}

impl FromFieldValue for ProjectStatus {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        match value {
            FieldValue::String(s) => match s.as_str() {
                "planning" => Ok(ProjectStatus::Planning),
                "in_progress" => Ok(ProjectStatus::InProgress),
                "on_hold" => Ok(ProjectStatus::OnHold),
                "completed" => Ok(ProjectStatus::Completed),
                "cancelled" => Ok(ProjectStatus::Cancelled),
                _ => Err(SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Unknown project status: {}", s),
                }),
            },
            _ => Err(SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!(
                    "Expected String for ProjectStatus, found {}",
                    value.type_name()
                ),
            }),
        }
    }
}

/// Project milestone struct
#[derive(Debug, Clone, PartialEq)]
pub struct Milestone {
    pub name: String,
    pub description: String,
    pub due_date: String, // Simplified as string for this example
    pub is_completed: bool,
    pub progress_percentage: f32,
    pub dependencies: Vec<String>,
}

impl StructSerializable for Milestone {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("description", &self.description)
            .field("due_date", &self.due_date)
            .field("is_completed", &self.is_completed)
            .field("progress_percentage", &self.progress_percentage)
            .field("dependencies", &self.dependencies)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let description = deserializer.field("description")?;
        let due_date = deserializer.field("due_date")?;
        let is_completed = deserializer.field("is_completed")?;
        let progress_percentage = deserializer.field("progress_percentage")?;
        let dependencies = deserializer.field("dependencies")?;

        Ok(Milestone {
            name,
            description,
            due_date,
            is_completed,
            progress_percentage,
            dependencies,
        })
    }
}

impl ToFieldValue for Milestone {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Milestone {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Milestone from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Milestone from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Milestone, found {}",
                value.type_name()
            ),
        })
    }
}

/// Company struct with basic collections and nesting
#[derive(Debug, Clone, PartialEq)]
pub struct Company {
    pub name: String,
    pub founded_year: i32,
    pub headquarters_city: String,
    pub headquarters_state: String,
    pub employee_count: usize,
    pub department_names: Vec<String>,
    pub active_project_names: Vec<String>,
    pub company_metadata: HashMap<String, String>,
}

impl StructSerializable for Company {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("founded_year", &self.founded_year)
            .field("headquarters_city", &self.headquarters_city)
            .field("headquarters_state", &self.headquarters_state)
            .field("employee_count", &self.employee_count)
            .field("department_names", &self.department_names)
            .field("active_project_names", &self.active_project_names)
            .field("company_metadata", &self.company_metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let founded_year = deserializer.field("founded_year")?;
        let headquarters_city = deserializer.field("headquarters_city")?;
        let headquarters_state = deserializer.field("headquarters_state")?;
        let employee_count = deserializer.field("employee_count")?;
        let department_names = deserializer.field("department_names")?;
        let active_project_names = deserializer.field("active_project_names")?;
        let company_metadata = deserializer.field("company_metadata")?;

        Ok(Company {
            name,
            founded_year,
            headquarters_city,
            headquarters_state,
            employee_count,
            department_names,
            active_project_names,
            company_metadata,
        })
    }
}

impl ToFieldValue for Company {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Company {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Company from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Company from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Company, found {}",
                value.type_name()
            ),
        })
    }
}

/// Department struct
#[derive(Debug, Clone, PartialEq)]
pub struct Department {
    pub name: String,
    pub manager: String,
    pub employee_count: u32,
    pub budget: f64,
    pub office_locations: Vec<Address>,
}

impl StructSerializable for Department {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("manager", &self.manager)
            .field("employee_count", &self.employee_count)
            .field("budget", &self.budget)
            .field("office_locations", &self.office_locations)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let manager = deserializer.field("manager")?;
        let employee_count = deserializer.field("employee_count")?;
        let budget = deserializer.field("budget")?;
        let office_locations = deserializer.field("office_locations")?;

        Ok(Department {
            name,
            manager,
            employee_count,
            budget,
            office_locations,
        })
    }
}

impl ToFieldValue for Department {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Department {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Department from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Department from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Department, found {}",
                value.type_name()
            ),
        })
    }

examples/serialization/error_handling.rs (line 117)

    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize VersionedData from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize VersionedData from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for VersionedData, found {}",
                value.type_name()
            ),
        })
    }
}

/// Validated user input with constraints
#[derive(Debug, Clone, PartialEq)]
pub struct ValidatedUserInput {
    pub username: String,
    pub email: String,
    pub age: u16,
    pub preferences: HashMap<String, String>,
}

impl StructSerializable for ValidatedUserInput {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("username", &self.username)
            .field("email", &self.email)
            .field("age", &self.age)
            .field("preferences", &self.preferences)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let username: String = deserializer.field("username")?;
        let email: String = deserializer.field("email")?;
        let age: u16 = deserializer.field("age")?;
        let preferences: HashMap<String, String> = deserializer.field("preferences")?;

        // Validate username
        if username.is_empty() || username.len() > 50 {
            return Err(SerializationError::ValidationFailed {
                field: "username".to_string(),
                message: "Username must be 1-50 characters long".to_string(),
            });
        }

        if !username
            .chars()
            .all(|c| c.is_alphanumeric() || c == '_' || c == '-')
        {
            return Err(SerializationError::ValidationFailed {
                field: "username".to_string(),
                message:
                    "Username can only contain alphanumeric characters, underscores, and hyphens"
                        .to_string(),
            });
        }

        // Validate email (basic check)
        if !email.contains('@') || !email.contains('.') || email.len() < 5 {
            return Err(SerializationError::ValidationFailed {
                field: "email".to_string(),
                message: "Invalid email format".to_string(),
            });
        }

        // Validate age
        if !(13..=120).contains(&age) {
            return Err(SerializationError::ValidationFailed {
                field: "age".to_string(),
                message: "Age must be between 13 and 120".to_string(),
            });
        }

        // Validate preferences
        if preferences.len() > 20 {
            return Err(SerializationError::ValidationFailed {
                field: "preferences".to_string(),
                message: "Too many preferences (maximum 20)".to_string(),
            });
        }

        for (key, value) in &preferences {
            if key.len() > 50 || value.len() > 200 {
                return Err(SerializationError::ValidationFailed {
                    field: "preferences".to_string(),
                    message: format!("Preference key/value too long: {}", key),
                });
            }
        }

        Ok(ValidatedUserInput {
            username,
            email,
            age,
            preferences,
        })
    }
}

impl ToFieldValue for ValidatedUserInput {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for ValidatedUserInput {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize ValidatedUserInput from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!(
                        "Failed to deserialize ValidatedUserInput from binary: {}",
                        e
                    ),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for ValidatedUserInput, found {}",
                value.type_name()
            ),
        })
    }
}

/// Recovery helper for handling partial data
#[derive(Debug, Clone, PartialEq)]
pub struct RecoverableData {
    pub critical_field: String,
    pub important_field: Option<String>,
    pub optional_field: Option<String>,
    pub metadata: HashMap<String, String>,
}

impl StructSerializable for RecoverableData {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("critical_field", &self.critical_field)
            .field("important_field", &self.important_field)
            .field("optional_field", &self.optional_field)
            .field("metadata", &self.metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        // Critical field - must exist
        let critical_field = deserializer.field("critical_field")?;

        // Important field - try to recover if missing
        let important_field = deserializer.field_optional("important_field")?;

        // Optional field - graceful fallback
        let optional_field = deserializer.field_optional("optional_field")?;

        // Metadata - recover what we can
        let metadata = deserializer.field_or("metadata", HashMap::new())?;

        Ok(RecoverableData {
            critical_field,
            important_field,
            optional_field,
            metadata,
        })
    }
}

impl ToFieldValue for RecoverableData {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for RecoverableData {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize RecoverableData from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize RecoverableData from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for RecoverableData, found {}",
                value.type_name()
            ),
        })
    }

examples/serialization/json_vs_binary.rs (line 113)

    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize PerformanceMetrics from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!(
                        "Failed to deserialize PerformanceMetrics from binary: {}",
                        e
                    ),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for PerformanceMetrics, found {}",
                value.type_name()
            ),
        })
    }
}

/// Large dataset for performance testing
#[derive(Debug, Clone, PartialEq)]
pub struct LargeDataset {
    pub name: String,
    pub values: Vec<f32>, // Changed from f64 to f32 (supported)
    pub labels: Vec<String>,
    pub feature_count: usize, // Simplified from Vec<Vec<f32>> to just a count
    pub feature_dimension: usize, // Store dimensions separately
    pub metadata: HashMap<String, String>,
    pub timestamp_count: usize, // Simplified from Vec<u64> to just count
}

impl StructSerializable for LargeDataset {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("values", &self.values)
            .field("labels", &self.labels)
            .field("feature_count", &self.feature_count)
            .field("feature_dimension", &self.feature_dimension)
            .field("metadata", &self.metadata)
            .field("timestamp_count", &self.timestamp_count)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let values = deserializer.field("values")?;
        let labels = deserializer.field("labels")?;
        let feature_count = deserializer.field("feature_count")?;
        let feature_dimension = deserializer.field("feature_dimension")?;
        let metadata = deserializer.field("metadata")?;
        let timestamp_count = deserializer.field("timestamp_count")?;

        Ok(LargeDataset {
            name,
            values,
            labels,
            feature_count,
            feature_dimension,
            metadata,
            timestamp_count,
        })
    }
}

impl ToFieldValue for LargeDataset {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for LargeDataset {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize LargeDataset from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize LargeDataset from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for LargeDataset, found {}",
                value.type_name()
            ),
        })
    }
}

/// Configuration data (typical JSON use case)
#[derive(Debug, Clone, PartialEq)]
pub struct Configuration {
    pub version: String,
    pub debug_enabled: bool,
    pub log_level: String,
    pub database_settings: HashMap<String, String>,
    pub feature_flags_enabled: bool, // Simplified from HashMap<String, bool>
    pub max_connections: f32,        // Simplified from HashMap<String, f64>
    pub timeout_seconds: f32,
}

impl StructSerializable for Configuration {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("version", &self.version)
            .field("debug_enabled", &self.debug_enabled)
            .field("log_level", &self.log_level)
            .field("database_settings", &self.database_settings)
            .field("feature_flags_enabled", &self.feature_flags_enabled)
            .field("max_connections", &self.max_connections)
            .field("timeout_seconds", &self.timeout_seconds)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let version = deserializer.field("version")?;
        let debug_enabled = deserializer.field("debug_enabled")?;
        let log_level = deserializer.field("log_level")?;
        let database_settings = deserializer.field("database_settings")?;
        let feature_flags_enabled = deserializer.field("feature_flags_enabled")?;
        let max_connections = deserializer.field("max_connections")?;
        let timeout_seconds = deserializer.field("timeout_seconds")?;

        Ok(Configuration {
            version,
            debug_enabled,
            log_level,
            database_settings,
            feature_flags_enabled,
            max_connections,
            timeout_seconds,
        })
    }
}

impl ToFieldValue for Configuration {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Configuration {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Configuration from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Configuration from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Configuration, found {}",
                value.type_name()
            ),
        })
    }

Trait Implementations

impl Clone for FieldValue

fn clone(&self) -> FieldValue

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FieldValue

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for FieldValue

fn eq(&self, other: &FieldValue) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for FieldValue