serde_with

The serde_as attribute provides a more flexible and composable alternative to Serde's standard with annotation. It allows you to mirror the type structure of a field and specify converters for inner types.

Key features:

• Inner Type Converters: You can specify converters for nested types, such as Vec<DisplayFromStr>.
• Placeholder Support: Use _ as a placeholder to restore the default de/serialization behavior for specific parts of a type (e.g., BTreeMap<_, DisplayFromStr>).
• Traits: The system is built on the SerializeAs and DeserializeAs traits.

Note: While more flexible, serde_as works with fewer types than the standard with annotation, though it aims to support all Rust Standard Library types in all combinations.

#[serde_as]
#[derive(Deserialize, Serialize)]
struct Data {
    // Use a specific converter for a field
    #[serde_as(as = "DisplayFromStr")]
    address: Ipv4Addr,

    // Use a complex converter with placeholders
    #[serde_as(as = "Map<DisplayFromStr, _>")]
    vec_as_map: Vec<(u32, String)>,
}

The #[apply] attribute allows you to apply specific Serde attributes to multiple fields within a struct or enum based on their types. This is useful for applying common attributes (like #[serde(default)] or #[serde(skip_serializing_if = "... ")]) to all fields of a certain type without repeating the attribute on every single field.

Syntax

The attribute follows a pattern of Type => Attribute. You can provide a comma-separated list of these rules:

#[apply(Type1 => Attribute1, Type2 => Attribute2)]

Type Matching Rules

• Generics: A type pattern without generics (e.g., Option) will match any instantiation of that type (e.g., Option<String>, Option<u8>).
• Wildcards: You can use _ as a wildcard in generic arguments (e.g., BTreeMap<_, u8> matches BTreeMap<String, u8>).
• Arrays: For array types [T; N], you can use _ for the length to match any length, or for the element type to match any element type.
• References: Patterns are relaxed regarding lifetimes and mutability. For example, &str will match &'static str or &'a mut str.
• Exclusion: You can skip applying attributes to a specific field by adding #[serde_with::skip_apply] to that field.

Customizing the Crate Path

By default, #[apply] assumes the attributes are part of the ::serde_with crate. If you are using a different path, you can specify it using the crate option:

#[apply(crate = "my_custom_serde_path", Type => Attribute)]

// Example usage (conceptual based on macro logic)
#[derive(Serialize, Deserialize)]
#[apply(
    Option<String> => #[serde(default)],
    u32 => #[serde(skip_serializing_if = "Option::is_none")]
)]
struct MyStruct {
    name: Option<String>, // Receives #[serde(default)]
    age: u32,             // Receives #[serde(skip_serializing_if = "Option::is_none")]
    id: String,          // Receives nothing
}

The #[serde_as] attribute is a more flexible and composable alternative to serde's #[serde(with = "...")]. It allows you to specify transformations for complex, nested types by mirroring the type structure of the field.

Key rules:

• Place #[serde_as] before the #[derive(Serialize, Deserialize)] attribute.
• Use #[serde_as(as = "...")] on fields to specify the transformation.
• Use _ as a placeholder to restore default de/serialization behavior for inner types (e.g., BTreeMap<_, DisplayFromStr>).
• Transformations are composed by mirroring the structure, such as Vec<DisplayFromStr> or Option<BTreeMap<_, Vec<DisplayFromStr>>>.

use serde::{Deserialize, Serialize};
use serde_with::{serde_as, DisplayFromStr};

#[serde_as]
#[derive(Serialize, Deserialize)]
struct A {
    #[serde_as(as = "DisplayFromStr")]
    mime: mime::Mime,
}

// Example of composition with nested structures
#[serde_as]
#[derive(Serialize, Deserialize)]
struct B {
    #[serde_as(as = "Option<BTreeMap<_, Vec<DisplayFromStr>>>")]
    mime: Option<BTreeMap<String, Vec<mime::Mime>>>,
}

When using the #[serde_as] attribute inside a procedural macro, you may need to specify the path to serde_with using the crate argument. This prevents users of your macro from having to manually add serde_with to their own Cargo.toml dependencies.

To do this, use #[serde_with::serde_as(crate = "...")]. This is typically used in conjunction with serde's own crate attribute to ensure the macro expands to the correct paths relative to the consumer's environment.

// Inside a procedural macro definition
#[proc_macro]
pub fn define_some_type(_item: TokenStream) -> TokenStream {
    let def = quote! {
        #[serde(crate = "::some_other_lib::serde")]
        #[::some_other_lib::serde_with::serde_as(crate = "::some_other_lib::serde_with")]
        #[derive(::some_other_lib::serde::Deserialize)]
        struct Data {
            #[serde_as(as = "_")]
            a: u32,
        }
    };

    TokenStream::from(def)
}

The KeyValueMap<T> helper allows you to serialize a sequence (like a Vec<T>) into a JSON/YAML map where each element of the sequence becomes a map entry.

To use this, you must define which part of your element serves as the map key:

1. For Structs: Use the #[serde(rename = "$key$")] attribute on the field you want to use as the key. The field named $key$ will be extracted as the map key, and all other fields will form the map value.
2. For Tuples, Tuple Structs, or Sequences: The first element is automatically used as the map key.
3. For Maps: The map-key that is named $key$ is used.

You apply this using the #[serde_as(as = "KeyValueMap<_>")] attribute on the field containing the sequence within a struct annotated with #[serde_as].

```rust
# #[cfg(feature = "macros")] {
# use serde::{Deserialize, Serialize};
# use serde_with::{serde_as, KeyValueMap};
#
# #[derive(Debug, Clone, PartialEq, Eq)]
# #[derive(Serialize, Deserialize)]
# struct SimpleStruct {
#     b: bool,
#     #[serde(rename = "$key$")]
#     id: String,
#     i: i32,
# }
#
# #[serde_as]
# # [derive(Debug, Clone, PartialEq, Eq)]
# #[derive(Serialize, Deserialize)]
# struct KVMap(#[serde_as(as = "KeyValueMap<_>")] Vec<SimpleStruct>);
#
# let values = KVMap(vec![
#     SimpleStruct { b: false, id: "id-0000".to_string(), i: 123 },
#     SimpleStruct { b: true, id: "id-0001".to_string(), i: 555 },
# ]);
#
# // Serializes to: {"id-0000": {"b": false, "i": 123}, "id-0001": {"b": true, "i": 555}}
# ```