7 unstable releases (3 breaking)

0.4.0 Feb 16, 2023
0.3.3 Feb 3, 2023
0.3.2 Jan 27, 2023
0.2.0 Jan 25, 2023
0.1.0 Jan 24, 2023

#663 in Text processing

49 downloads per month
Used in seaplane


368 lines

Container Image Reference

Rust Version crates.io Dependency Status

A library for using and handling Seaplane Object IDs.


An Object ID (OID) is a RFC4648 base32 (no padding) extended hex-encoded UUID with a prefix separated by a -.

For example tst-0ous781p4lu7v000pa2a2bn1gc, by convention the prefix is three ASCII lowercase characters, however that is a hard constraint of OIDs in general. The current implementation limits prefixes to 3 characters, but prefix limit could be exposed as a tunable if that need arises.

The Pitch

OIDs allow a "human readable subject line" in the form of the prefix, where actual data is a UUID. This means while debugging or reviewing a system it's trivial to determine if an incorrect OID was passed in a particular location by looking at the prefix. This isn't easily achievable with bare UUIDs.

Base32 encoding the UUID also allows compressing the data into a smaller and more familiar format for humans, akin to a commit hash.

The Anti-Pitch

The downside to OIDs is a layer of indirection when handling IDs and values, it's not immediately obvious that the OIDs are a prefixed UUID. Additionally, the prefixes must be controlled in some manner including migrated on changes which adds a layer of complexity at the application layer.

There is also additional processing overhead compared to a bare UUID in order to encode/decode as well as handling the appending and removing the prefixes.

However, we believe the drawbacks to pale in comparison to the benefits derived from the format.


use seaplane_oid::{error::*, Oid};

fn main() -> Result<()> {
    // OIDs can be created with a given prefix alone, which generates a new
    // UUID
    let oid = Oid::new("exm")?;

    // OIDs can be parsed from strings, however the "value" must be a valid
    // base32 encoded UUID
    let oid: Oid = "tst-0ous781p4lu7v000pa2a2bn1gc".parse()?;

    // OIDs can also be created from the raw parts
    let oid = Oid::with_uuid(

    // One can retrieve the various parts of the OID if needed
    println!("Prefix: {}", oid.prefix());
    println!("Value: {}", oid.value());
    println!("UUID: {}", oid.uuid());



Licensed under the Apache License, Version 2.0, LICENSE. Copyright 2023 Seaplane IO, Inc.


~26K SLoC