Module bson::uuid

UUID support for BSON.

The crate::Uuid type

The BSON format supports UUIDs via the “binary” type with the UUID subtype (4). To facilitate working with these UUID-subtyped binary values, this crate provides a crate::Uuid type, whose serde implementation automatically serializes to and deserializes from binary values with subtype 4.

The popular uuid crate also provides a UUID type, though its serde implementation does not produce or parse subtype 4 binary values. Instead, when serialized with bson::to_bson, it produces as a string, and when serialized with bson::to_vec, it produces a binary value with subtype 0 rather than 4. Because of this, it is highly recommended to use the crate::Uuid type when working with BSON instead of the uuid crate’s Uuid, since crate::Uuid correctly produces subtype 4 binary values via either serialization function.

e.g.

use serde::{Serialize, Deserialize};
use bson::doc;

#[derive(Serialize, Deserialize)]
struct Foo {
    /// serializes as a String or subtype 0 BSON binary, depending
    /// on whether `bson::to_bson` or `bson::to_vec` is used.
    uuid: uuid::Uuid,

    /// serializes as a BSON binary with subtype 4 when either is used.
    bson_uuid: bson::Uuid,

    /// serializes as a BSON binary with subtype 4 when either is used.
    /// this requires the "uuid-1" feature flag
    #[serde(with = "bson::serde_helpers::uuid_1_as_binary")]
    uuid_as_bson: uuid::Uuid,
}

The uuid-1 feature flag

To facilitate the conversion between crate::Uuid values and the uuid crate’s Uuid values, the uuid-1 feature flag can be enabled. This flag exposes a number of convenient conversions, including the crate::Uuid::to_uuid_1 method and the From<uuid::Uuid> implementation for Bson, which allows the uuid crate’s Uuid values to be used in the doc! and bson! macros.

use bson::doc;

// this automatic conversion does not require any feature flags
let query = doc! {
    "uuid": bson::Uuid::new(),
};

// but this automatic conversion requires the "uuid-1" feature flag
let query = doc! {
    "uuid": uuid::Uuid::new_v4(),
};

// this also requires the "uuid-1" feature flag.
let uuid = bson::Uuid::new().to_uuid_1();

For backwards compatibility, a uuid-0_8 feature flag can be enabled, which provides the same API for interoperation with version 0.8 of the uuid crate.

The serde_with-3 feature flag

The serde_with-3 feature can be enabled to support more ergonomic serde attributes for (de)serializing uuid::Uuid from/to BSON via the serde_with crate. The main benefit of this compared to the regular serde_helpers is that serde_with-3 can handle nested uuid::Uuid values (e.g. in Option), whereas the former only works on fields that are exactly uuid::Uuid.

use serde::{Deserialize, Serialize};
use bson::doc;

#[serde_with_3::serde_as]
#[derive(Deserialize, Serialize, PartialEq, Debug)]
struct Foo {
  /// Serializes as a BSON binary rather than using [`uuid::Uuid`]'s serialization
  #[serde_as(as = "Option<bson::Uuid>")]
  as_bson: Option<uuid::Uuid>,
}

let foo = Foo {
  as_bson: Some(uuid::Uuid::new_v4()),
};

let expected = doc! {
  "as_bson": bson::Uuid::from(foo.as_bson.unwrap()),
};

assert_eq!(bson::to_document(&foo)?, expected);

Using crate::Uuid with non-BSON formats

crate::Uuid’s serde implementation is the same as uuid::Uuid’s for non-BSON formats such as JSON:

use serde_json::json;

let uuid = uuid::Uuid::new_v4();
let bson_uuid: bson::Uuid = uuid.into();
let foo = Foo { uuid, bson_uuid, };

let json = serde_json::to_value(&foo)?;
assert_eq!(json, json!({ "uuid": uuid.to_string(), "bson_uuid": uuid.to_string() }));

Structs

• Uuid
  A struct modeling a BSON UUID value (i.e. a Binary value with subtype 4).

Enums

• Error
  Errors that can occur during Uuid construction and generation.
• UuidRepresentation
  Enum of the possible representations to use when converting between Uuid and Binary. This enum is necessary because the different drivers used to have different ways of encoding UUIDs, with the BSON subtype: 0x03 (UUID old). If a UUID has been serialized with a particular representation, it MUST be deserialized with the same representation.

Type Aliases

• Result
  Alias for Result<T, bson::uuid::Error>.