Module serde_with::guide[][src]

Expand description

serde_with User Guide

This crate provides helper functions to extend and change how serde serializes different datatypes. For example, you can serialize a map as a sequence of tuples, serialize using the Display and FromStr traits, or serialize an empty String like None. serde_with covers types from the Rust Standard Library and some common crates like chrono.

A list of all supported transformations is available on this page.

The crate offers four types of functionality.

1. A more flexible and composable replacement for the with annotation, called serde_as (v1.5.0+)

This is an alternative to serde’s with-annotation, which adds flexibility and composability to the scheme. The main downside is that it work with fewer types than with-annotations. However, all types from the Rust Standard Library should be supported in all combinations and any missing entry is a bug.

The serde_as scheme is based on two new traits: SerializeAs and DeserializeAs.
Check out the detailed page about serde_as and the available features.

Example

#[serde_as]
#[derive(Deserialize, Serialize)]
struct Data {
    // Type does not implement Serialize or Deserialize
    #[serde_as(as = "DisplayFromStr")]
    address: Ipv4Addr,
    // Treat the Vec like a map with duplicates
    // Convert u32 into a String and keep the String the same type
    #[serde_as(as = "HashMap<DisplayFromStr, _>")]
    vec_as_map: Vec<(u32, String)>,
}

let data = Data {
    address: Ipv4Addr::new(192, 168, 0, 1),
    vec_as_map: vec![
        (123, "Hello".into()),
        (456, "World".into()),
        (123, "Hello".into()),
    ],
};

let json = r#"{
  "address": "192.168.0.1",
  "vec_as_map": {
    "123": "Hello",
    "456": "World",
    "123": "Hello"
  }
}"#;

// Test Serialization
assert_eq!(json, serde_json::to_string_pretty(&data).unwrap());
// Test Deserialization
assert_eq!(data, serde_json::from_str(json).unwrap());

2. Integration with serde’s with-annotation

serde’s with-annotation allows to specify a different serialization or deserialization function for a field. It is useful to adapt the serialization of existing types to the requirements of a protocol. Most modules in this crate can be used together with the with-annotation.

The annotation approach has one big drawback, in that it is very inflexible. It allows specifying arbitrary serialization code, but the code has to perform the correct transformations. It is not possible to combine multiple of those functions. One common use case for this is the serialization of collections like Vec. If you have a field of type T, you can apply the with-annotation, but if you have a field of type Vec<T>, there is no way to re-use the same functions for the with-annotation. This inflexibility is fixed in the serde_as scheme presented above.

The example shows a similar setup as in the serde_as example above, but using the with-annotation.

Example

#[derive(Deserialize, Serialize)]
struct Data {
    // Type does not implement Serialize or Deserialize
    #[serde(with = "serde_with::rust::display_fromstr")]
    address: Ipv4Addr,
    // Treat the Vec like a map with duplicates
    #[serde(with = "serde_with::rust::tuple_list_as_map")]
    vec_as_map: Vec<(String, u32)>,
}

let data = Data {
    address: Ipv4Addr::new(192, 168, 0, 1),
    vec_as_map: vec![
        ("Hello".into(), 123),
        ("World".into(), 456),
        ("Hello".into(), 123),
    ],
};

let json = r#"{
  "address": "192.168.0.1",
  "vec_as_map": {
    "Hello": 123,
    "World": 456,
    "Hello": 123
  }
}"#;

// Test Serialization
assert_eq!(json, serde_json::to_string_pretty(&data).unwrap());
// Test Deserialization
assert_eq!(data, serde_json::from_str(json).unwrap());

3. proc-macros to make it easier to use both above parts

The proc-macros are an optional addition and improve the user experience for common tasks. We have already seen how the serde_as attribute is used to define the serialization instructions.

The proc-macro attributes are defined in the serde_with_macros crate and re-exported from the root of this crate. The proc-macros are optional, but enabled by default. For further details, please refer to the documentation of each proc-macro.

4. Derive macros to implement Deserialize and Serialize

The derive macros work similar to the serde provided ones but they do implement other de/serialization schemes. For example, the derives DeserializeFromStr and SerializeDisplay require that the type also implement FromStr and Display and de/serializes from/to a string instead of the usual way of iterating over all fields.

Migrating from the with-annotations to serde_as

Each old style module explains how it can be converted to serde_as. Not all modules have such a description since not all are migrated and some are hard to implement in the serde_as system.

Modules

Available Feature Flags

serde_as Annotation

De/Serialize Transformations Available