[−][src]Crate serde_with

This crate provides custom de/serialization helpers to use in combination with serde's with-annotation and with the improved serde_as-annotation. Some common use cases are:

De/Serializing a type using the Display and FromStr traits, e.g., for u8, url::Url, or mime::Mime. Check DisplayFromStr or serde_with::rust::display_fromstr for details.
Skip serializing all empty Option types with #[skip_serializing_none].
Apply a prefix to each field name of a struct, without changing the de/serialize implementations of the struct using with_prefix!.
Deserialize a comma separated list like #hash,#tags,#are,#great into a Vec<String>. Check the documentation for serde_with::rust::StringWithSeparator::<CommaSeparator>.

Check out the user guide to find out more tips and tricks about this crate.

Use `serde_with` in your Project

Add this to your Cargo.toml:

[dependencies.serde_with]
version = "1.5.1"
features = [ "..." ]

The crate contains different features for integration with other common crates. Check the feature flags section for information about all available features.

Examples

Annotate your struct or enum to enable the custom de/serializer.

`DisplayFromStr`

#[serde_as]
#[derive(Deserialize, Serialize)]
struct Foo {
    // Serialize with Display, deserialize with FromStr
    #[serde_as(as = "DisplayFromStr")]
    bar: u8,
}

// This will serialize
Foo {bar: 12}

// into this JSON
{"bar": "12"}

`skip_serializing_none`

This situation often occurs with JSON, but other formats also support optional fields. If many fields are optional, putting the annotations on the structs can become tedious.

#[skip_serializing_none]
#[derive(Deserialize, Serialize)]
struct Foo {
    a: Option<usize>,
    b: Option<usize>,
    c: Option<usize>,
    d: Option<usize>,
    e: Option<usize>,
    f: Option<usize>,
    g: Option<usize>,
}

// This will serialize
Foo {a: None, b: None, c: None, d: Some(4), e: None, f: None, g: Some(7)}

// into this JSON
{"d": 4, "g": 7}

Advanced `serde_as` usage

This example is mainly supposed to highlight the flexibility of the serde_as-annotation compared to serde's with-annotation. More details about serde_as can be found in the user guide.

#[serde_as]
#[derive(Deserialize, Serialize)]
struct Foo {
     // Serialize them into a list of number as seconds
     #[serde_as(as = "Vec<DurationSeconds>")]
     durations: Vec<Duration>,
     // We can treat a Vec like a map with duplicates.
     // JSON only allows string keys, so convert i32 to strings
     // The bytes will be hex encoded
     #[serde_as(as = "BTreeMap<DisplayFromStr, Hex>")]
     bytes: Vec<(i32, Vec<u8>)>,
}

// This will serialize
Foo {
    durations: vec![Duration::new(5, 0), Duration::new(3600, 0), Duration::new(0, 0)],
    bytes: vec![
        (1, vec![0, 1, 2]),
        (-100, vec![100, 200, 255]),
        (1, vec![0, 111, 222]),
    ],
}

// into this JSON
{
    "durations": [5, 3600, 0],
    "bytes": {
        "1": "000102",
        "-100": "64c8ff",
        "1": "006fde"
    }
}

Modules

chrono	De/Serialization of chrono types
de	Module for `DeserializeAs` implementations
formats	Specify the format and how lenient the deserialization is
guide	`serde_with` User Guide
hex	De/Serialization of hexadecimal encoded bytes
json	De/Serialization of JSON
rust	De/Serialization for Rust's builtin and std types
ser	Module for `SerializeAs` implementations

Macros

flattened_maybe	Support deserializing from flattened and non-flattened representation
with_prefix	Serialize with an added prefix on every field name and deserialize by trimming away the prefix.

Structs

As	Adapter to convert from `serde_as` to the serde traits.
BytesOrString	Deserialize from bytes or string
CommaSeparator	Predefined separator using a single comma
DefaultOnError	Deserialize value and return `Default` on error
DisplayFromStr	De/Serialize using `Display` and `FromStr` implementation
DurationSeconds	De/Serialize Durations as number of seconds.
DurationSecondsWithFrac	De/Serialize Durations as number of seconds.
NoneAsEmptyString	De/Serialize a `Option<String>` type while transforming the empty string to `None`
Same	Adapter to convert from `serde_as` to the serde traits.
SpaceSeparator	Predefined separator using a single space
StringWithSeparator	De/Serialize a delimited collection using `Display` and `FromStr` implementation
TimestampSeconds	De/Serialize timestamps as seconds since the UNIX epoch
TimestampSecondsWithFrac	De/Serialize timestamps as seconds since the UNIX epoch

Traits

DeserializeAs	A data structure that can be deserialized from any data format supported by Serde, analogue to `Deserialize`.
Separator	Separator for string-based collection de/serialization
SerializeAs	A data structure that can be serialized into any data format supported by Serde, analogue to `Serialize`.

Attribute Macros

serde_as	Convenience macro to use the `serde_as` system.
skip_serializing_none	Add `skip_serializing_if` annotations to `Option` fields.

Derive Macros

DeserializeFromStr	Deserialize value by using it's `FromStr` implementation
SerializeDisplay	Serialize value by using it's `Display` implementation