SUUID System in sdata: A Semantic Alternative to Standard UUIDs

The SUUID (Super‑Universally Unique Identifier) system is a semantic UUID implementation that embeds class names and human‑readable identifiers into a Base64‑encoded string, enabling deterministic generation and intrinsic object traceability that standard UUIDs cannot provide.

The lepy/sdata library implements the SUUID system in sdata/suuid.py to replace opaque 128‑bit identifiers with self‑describing keys. Unlike standard UUIDs that rely solely on randomness or namespace hashing, SUUIDs concatenate a hexadecimal UUID with metadata to create deterministic, content‑addressed identifiers for every object in the ecosystem.

Core Components of the SUUID System

In sdata/suuid.py, the SUUID class defines a three‑part identifier that extends the traditional UUID format with semantic meaning.

The Three‑Part Structure

Every SUUID consists of:

• HUUUID – A 32‑character hexadecimal UUID representing the raw 128‑bit value (self.huuid).
• class_name – A plain string denoting the logical class of the object (e.g., Data, Image).
• name – A safe filename string providing a human‑readable identifier (e.g., experiment_01).

These components are concatenated using a double‑underscore separator (SEP = "__") and Base64‑encoded to produce the final public identifier. The encoding scheme follows:

suuid_bytes = base64.b64encode(f"{huuid}{class_name}__{name}".encode())
suuid_str = suuid_bytes.decode().strip()

The sname Property

For human readability, the SUUID class exposes an sname attribute formatted as class_name__name__huuid. This string places the semantic information first, making it immediately obvious what object type the identifier represents without decoding the Base64 payload.

SUUID vs Standard UUID: Key Differences

The SUUID system diverges from Python’s standard uuid.UUID in four critical ways:

Feature	Standard UUID	SUUID (SUUID)
Semantic Content	No embedded meaning; pure 128‑bit value	Stores class_name and name alongside the UUID
Deterministic Creation	Only uuid5() supports deterministic generation; still yields opaque hex	SUUID.from_name() creates deterministic identifiers from class and name inputs, guaranteeing the same UID for the same logical object
Representation	Hexadecimal string (xxxxxxxx‑xxxx‑xxxx‑xxxx‑xxxxxxxxxxxx)	URL‑safe Base64 string (suuid_str) with human‑readable sname variant
Integration	Stored in generic metadata fields	Automatically assigned to every sdata object via sdata/base.py, providing built‑in traceability

Creating and Using SUUIDs in sdata

The SUUID class provides factory methods for different creation scenarios, each optimized for specific data provenance requirements.

Deterministic Generation from Class and Name

To create a reproducible identifier from logical attributes, use SUUID.from_name() (lines 194‑199 in sdata/suuid.py):

from sdata import SUUID

sid = SUUID.from_name(class_name="MyClass", name="MyObject")
print(sid.suuid_str)  # NzhiyzJiZjcz... (Base64)

print(sid.sname)      # MyClass__myobject__78bc2bf7390...

This method guarantees that identical class_name and name inputs always produce the same SUUID, enabling idempotent data operations.

Content‑Addressed Identifiers from Files

For data integrity verification, SUUID.from_file() (lines 212‑222) generates an SUUID from the MD5 hash of a file’s contents:

sid = SUUID.from_file(class_name="File", filepath="/path/to/data.csv")
print(sid.sname)  # File__data_csv__a1b2c3d4...

This creates a content‑addressable storage system where the identifier inherently reflects the file’s binary state.

Converting Standard UUIDs

Existing uuid.UUID objects can be promoted to SUUIDs using SUUID.from_uuid() (lines 177‑180):

import uuid
from sdata import SUUID

uid = uuid.uuid4()
sid = SUUID.from_uuid(class_name="Dataset", uuid_obj=uid)
print(sid.sname)  # Dataset__<empty>__<uid.hex>

Parsing and Serialization

To reconstruct an SUUID from its Base64 representation, use SUUID.from_suuid_str() (lines 239‑242):

encoded = sid.suuid_str
sid2 = SUUID.from_suuid_str(encoded)
assert sid2.sname == sid.sname

For metadata serialization, SUUID.to_dict() (lines 151‑159) exports all components as a dictionary:

info = sid.to_dict()

# {'class_name': 'MyClass', 'name': 'myobject', 'huuid': '78bc2bf7390...', 

#  'suuid': 'NzhiyzJi...', 'sname': 'MyClass__myobject__78bc2bf7390...'}

Integration with the sdata Object Model

The SUUID system is not merely a utility class; it is deeply integrated into the sdata object lifecycle. In sdata/base.py, every sdata object automatically receives a suuid attribute upon instantiation, along with a convenience sname property. This automatic assignment ensures that all datasets, images, and derived objects carry intrinsic traceability without manual UUID management, making dataset lineage and cross‑reference operations trivial.

Summary

• SUUIDs are semantic identifiers that combine a 128‑bit UUID with class_name and name metadata.
• They use Base64 encoding for the canonical suuid_str and offer a human‑readable sname format.
• Deterministic generation via from_name() enables reproducible identifiers for the same logical entities.
• Content‑addressed creation via from_file() binds identifiers to file contents for integrity verification.
• Automatic integration in sdata/base.py provides every object with built‑in traceability.

Frequently Asked Questions

What does SUUID stand for?

SUUID stands for Super‑Universally Unique Identifier. It represents the implementation class (SUUID) of the broader SUID (Super‑Universally Unique Identifier) system defined in the sdata library.

How does SUUID differ from UUID4?

While UUID4 generates purely random 128‑bit identifiers with no embedded meaning, SUUID always includes the object’s class and name within the identifier. Additionally, SUUIDs are Base64‑encoded rather than hexadecimal, and they support deterministic creation from semantic inputs rather than relying solely on randomness.

Can SUUIDs be decoded to recover the original components?

Yes. Because the SUUID stores the concatenation of huuid, class_name, and name before Base64 encoding, you can recover these components using SUUID.from_suuid_str() to reconstruct the object, or access the sname property directly to view the human‑readable format without decoding.

How are SUUIDs automatically assigned to sdata objects?

According to the implementation in sdata/base.py, every class inheriting from the base sdata object automatically instantiates an SUUID during initialization. This assigns both a suuid attribute (the SUUID object itself) and an sname attribute (the readable string), ensuring consistent identification across the entire sdata ecosystem without manual intervention.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}