UUID v8 Custom Generator

UUID v8: the customisable UUID

UUID version 8 is the new "custom" UUID format formally introduced by RFC 9562 in May 2024, the same RFC that standardised v6 and v7. It carves out 122 bits of the 128-bit UUID space for the application to define however it wants, while keeping the wire format and parsers of every other UUID version untouched.

Fixed and free bits

Only 6 bits are reserved: 4 bits for the version nibble (1000 = 8) at the 13th character, and 2 bits for the variant (10) at the 17th. The other 122 bits are entirely yours to design — a near-empty canvas inside the most ubiquitous ID format in software.

xxxxxxxx-xxxx-8xxx-yxxx-xxxxxxxxxxxx
                  ^   ^
                  ver variant (10xx)

Useful custom layouts

• 48-bit timestamp + 14-bit tenant + 60-bit random — sharded multi-tenant SaaS, sortable per tenant.
• 48-bit timestamp + 80-bit hash — content-addressed IDs in UUID format, similar to git object hashes.
• 32-bit type tag + 90-bit random — self-describing IDs where the type is encoded in the prefix.
• Custom epoch + node-id + counter — a Snowflake-style ID dressed as a standard UUID.

v8 vs v7

UUID v7 is the standardised, opinionated time-ordered UUID — 48 bits of Unix milliseconds followed by random. Pick v7 when you want sortability without thinking. UUID v8 is for when v7 doesn't fit your domain — when you need to embed a tenant id, a shard, a content hash or any other domain-specific signal. v7 is the safe default; v8 is the escape hatch.

Compatibility and parser support

Every standard UUID parser accepts v8 — it is just a UUID with a different version nibble. PostgreSQL's uuid type, JavaScript's crypto.randomUUID() consumers, Java's UUID.fromString(), Python's uuid.UUID — they all accept v8. The catch: most libraries don't generate v8 out of the box. Use uuidv8 (JS), uuid Rust crate, or hand-roll the bit layout.

Pitfalls and best practices

• Always include random bits — fully deterministic v8 layouts collide easily.
• Document your bit layout in your engineering wiki; otherwise nobody else can decode it.
• Version your scheme — encode a layout version in the first nibble so you can evolve without breaking old IDs.
• Beware predictability — if business logic leaks into the ID, an attacker may enumerate.
• Don't use v8 for security tokens — use a CSPRNG with at least 128 bits of entropy.

FAQ

When should I use v8 instead of v7? When you need to customise the layout — embed a tenant id, a shard key, a content hash. If you just want sortable random IDs, v7 is simpler and better-supported.

What's the risk of v8? A bad layout can break uniqueness or leak information. With great freedom comes great responsibility — design carefully and always include random bits.

Is v8 a standard UUID format? Yes — RFC 9562 includes v8 explicitly, and every UUID parser will accept it as a valid UUID. The wire format stays 128 bits in 8-4-4-4-12.

Can I use v8 as a primary key? Yes, as long as your layout is unique and stable. Many teams use a v8 layout that mimics v7 but adds a 14-16-bit shard tag for partitioning.