UUID

Luma provides UUID generation and validation through the uuid namespace.
Generate unique identifiers for database records, session tokens, request tracing, and more.
No imports, no setup — just call uuid.v4() and get a standard UUID string.

Generate a random UUID (v4)

id: str = uuid.v4()

Returns a random UUID in standard format: "550e8400-e29b-41d4-a716-446655440000".

Version 4 UUIDs are generated from cryptographically secure random bytes. Every call produces a globally unique identifier. This is the most common UUID version — use it when you need a unique ID and don’t care about ordering.

// Database record ID
user_id: str = uuid.v4()
print("Created user: ${user_id}")

// Session token
session: str = uuid.v4()
print("Session: ${session}")

// Request tracing
request_id: str = uuid.v4()
print("Processing request ${request_id}")

Generate a time-ordered UUID (v7)

id: str = uuid.v7()

Returns a time-ordered UUID: "018f3e5c-8a01-7b12-a456-426614174000".

Version 7 UUIDs encode a millisecond-precision timestamp in the first 48 bits, followed by random bytes. This means v7 UUIDs sort chronologically — IDs created later are always lexicographically greater than IDs created earlier.

// Database primary keys that sort by creation time
id1: str = uuid.v7()
id2: str = uuid.v7()
// id2 > id1 is always true

Use v7 when UUIDs will be used as database primary keys. B-tree indexes perform significantly better with sequential inserts than with random inserts. v7 gives you the uniqueness of UUIDs with the insert performance of auto-increment IDs.

When to use v4 vs v7

When in doubt, use uuid.v4(). Use uuid.v7() when ordering matters.

Validate a UUID

valid: bool = uuid.is_valid(s)

Returns true if the string is a valid UUID in standard 8-4-4-4-12 hexadecimal format. Accepts any UUID version (v1–v7).

uuid.is_valid("550e8400-e29b-41d4-a716-446655440000")   // true
uuid.is_valid("not-a-uuid")                              // false
uuid.is_valid("")                                        // false
uuid.is_valid("550e8400e29b41d4a716446655440000")        // false (missing dashes)

Use it to validate user input before storing or processing:

input: str = "550e8400-e29b-41d4-a716-446655440000"
if !uuid.is_valid(input) {
    error("Invalid UUID format")
}

UUID format

All UUIDs follow the standard RFC 9562 format:

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

• 36 characters total (32 hex digits + 4 dashes)
• Lowercase hexadecimal
• Dashes at positions 8, 13, 18, 23
• Example: 550e8400-e29b-41d4-a716-446655440000

Examples

Database records

fn create_user(name: str) -> {str: str} {
    return {
        "id": uuid.v7(),
        "name": name
    }
}

user: {str: str} = create_user("Alice")
print("User ${user["name"]} created with ID ${user["id"]}")

Batch processing with tracing

batch_id: str = uuid.v4()
print("Starting batch ${batch_id}")

items: [str] = ["order-1", "order-2", "order-3"]
items.walk(item) -> {
    item_id: str = uuid.v4()
    print("[${batch_id}] Processing ${item} as ${item_id}")
}

print("Batch ${batch_id} complete")

Input validation

fn parse_uuid(input: str) -> str {
    if !uuid.is_valid(input) {
        error("Expected a valid UUID, got: ${input}")
    }
    return input
}

Playground

Try UUID functions live in the Luma Playground:

• UUID: Generate v4 (Random) — generate random UUIDs and see the output
• UUID: Generate v7 (Time-Ordered) — generate time-ordered UUIDs and observe chronological sorting
• UUID: Validate Format — test validation against valid and invalid strings

Method summary

Error handling

Design notes

• uuid is a namespace, not a type — functions are stateless, no object to create
• UUIDs are returned as strings in standard lowercase 8-4-4-4-12 format — the universal interchange format
• uuid.v4() uses crypto/rand internally — the same OS-level secure random source as crypto.rand(). UUIDs are not predictable
• uuid.v7() uses the system clock for the timestamp component and crypto/rand for the random component
• No parsing API — UUIDs are strings. If you receive a valid UUID string, it’s already ready to use
• No UUID type — a dedicated type would add complexity without meaningful benefit. Strings compare, concatenate, and serialize naturally
• v1, v3, v5 not included — v1 leaks MAC addresses (privacy concern), v3/v5 are name-based (niche use). Can be added later if there’s real demand