Structuring Data with Serde in Rust

#Serde Helper Functions

Sometimes you may want to serialize or deserialize data in your structs or enums differently than the default behavior. Serde provides serialize_with and deserialize_with attributes that allow you to specify functions to use for serialization and deserialization on specific fields and variants.

The BSON library now includes a set of functions that implement common strategies for custom serialization and deserialization when working with BSON. You can use these functions by importing them from the serde_helpers module in the bson-rust crate and using the serialize_with and deserialize_with attributes. A few of these functions are detailed below.

Some users prefer to represent the object ID field in their data with a hexidecimal string rather than the BSON library ObjectId type:

1
#[derive(Serialize, Deserialize)]
2
    struct Item {
3
    oid: String,
4
    // rest of fields
5
}

We've introduced a method for serializing a hex string into an ObjectId in the serde_helpers module called serialize_hex_string_as_object_id. I can annotate my oid field with this function using serialize_with:

1
#[derive(Serialize, Deserialize)]
2
struct Item {
3
    #[serde(serialize_with = "serialize_hex_string_as_object_id")]
4
    oid: String,
5
    // rest of fields
6
}

Now, if I serialize an instance of the Item struct into BSON, the oid field will be represented by an ObjectId rather than a string.

We've also introduced modules that take care of both serialization and deserialization. For instance, I might want to represent binary data using the Uuid type in the Rust uuid crate:

1
#[derive(Serialize, Deserialize)]
2
struct Item {
3
    uuid: Uuid,
4
    // rest of fields
5
}

Since BSON doesn't have a specific UUID type, I'll need to convert this data into binary if I want to serialize into BSON. I'll also want to convert back to Uuid when deserializing from BSON. The uuid_as_binary module in the serde_helpers module can take care of both of these conversions. I'll add the following attribute to use this module:

1
#[derive(Serialize, Deserialize)]
2
struct Item {
3
    #[serde(with = "uuid_as_binary")]
4
    uuid: Uuid,
5
    // rest of fields
6
}

Now, I can work directly with the Uuid type without needing to worry about how to convert it to and from BSON!

The serde_helpers module introduces functions for several other common strategies; you can check out the documentation here.

#Unsigned Integers

The BSON specification defines two integer types: a signed 32 bit integer and a signed 64 bit integer. This can prevent challenges when you attempt to insert data with unsigned integers into your collections.

My Student struct from the previous example contains unsigned integers in the grade and test_score fields. Previous versions of the BSON library would return an error if I attempted to serialize an instance of this struct into Document, since there isn't always a clear mapping between unsigned and signed integer types. However, many unsigned integers can fit into signed types! For example, I might want to create the following student:

1
let student = Student {
2
    name: "Alyson".to_string(),
3
    grade: 11,
4
    test_scores: vec![89, 92, 99],
5
};

While the numbers in the grade and test_scores fields are technically unsigned 32 bit integers, they can be converted to signed 32 bit integers without losing any data.

The 1.2.0 release of the BSON library no longer returns an error when attempting to serialize unsigned integers into BSON, and instead tries to perform a lossless conversion into one of the signed integer BSON types. If the unsigned integer cannot be converted to a signed 32 bit or 64 bit integer, serialization will still return an error.

Now, I can convert my student struct into a Document:

1
let doc = to_document(&student)?;

I can use println! to see the following Document is returned:

1
Document({
2
    "name": String("Alyson"),
3
    "grade": Int32(11),
4
    "test_scores": Array([Int32(89), Int32(92), Int32(99)])
5
})