UUID v8 — Custom Layout for Application-Specific Identifiers

RFC 9562, published in May 2024, introduced three new UUID versions alongside the widely discussed v7. UUID v8 is the least prescribed of the three — only 6 bits are fixed by the standard, leaving 122 bits for the application to define. This makes it the escape hatch for use cases that do not fit v4 or v7.

What RFC 9562 Specifies for v8

The version nibble at bits 76–79 must be 1000 (hex 8), and the variant bits at bits 64–65 must be 10 (RFC 4122 variant). Everything else — all 122 remaining bits — is application-defined. The standard explicitly states that the internal layout is not interoperable across implementations unless separately documented.

When to Use UUID v8

UUID v8 makes sense when you need to:

• Embed a non-standard timestamp: A nanosecond or microsecond timestamp, a custom epoch, or a Tai64 timestamp rather than Unix milliseconds.
• Encode shard or region metadata: Embed a datacenter ID, shard key, or geographic region in the high bits for routing purposes.
• Adopt an existing proprietary format: Systems that already have a 128-bit ID format (e.g., Snowflake, KSUID) can re-encode values as UUID v8 to expose them through UUID-typed columns and APIs without changing the data.
• Versioned identifiers: Embed a schema version into the ID itself, useful for self-describing records in append-only event stores.

A Practical Layout Example

A common UUID v8 layout for high-throughput services:

This layout gives millisecond time-ordering (like v7) while also embedding a shard ID for routing — something v7 does not support without out-of-band metadata.

UUID v8 in Practice

No standard library generates UUID v8 automatically — by definition the layout must be custom. Generation requires manual bit manipulation:

function uuidV8(shardId) {
  const ms = BigInt(Date.now());
  const rand = crypto.getRandomValues(new Uint8Array(8));
  const randBig = rand.reduce((acc, b) => (acc << 8n) | BigInt(b), 0n);

  // version nibble = 8 at bits 76-79, variant = 0b10 at bits 64-65
  const high = (ms << 16n) | 0x8000n | BigInt(shardId & 0xfff);
  const low = (0x8000000000000000n) | (randBig & 0x3fffffffffffffffn);

  const hex = high.toString(16).padStart(16, '0') + low.toString(16).padStart(16, '0');
  return `${hex.slice(0,8)}-${hex.slice(8,12)}-${hex.slice(12,16)}-${hex.slice(16,20)}-${hex.slice(20)}`;
}

Interoperability Considerations

UUID v8 values are valid UUIDs — any system that accepts a UUID string will store and return a v8 value without error. However, the meaning of the bits is opaque to consumers unless the layout is documented. If you expose UUID v8 identifiers in a public API, document the bit layout in your API reference so consumers can extract embedded metadata if needed.

For internal systems where all consumers share the same codebase, UUID v8 is a clean way to pack more information into an ID without a separate metadata field.

Related Resources

• RFC 9562 §5.8 — UUID v8 specification
• Timeflake — a UUID-compatible 128-bit ID with custom timestamp precision
• ULID specification — alternative sortable ID format that inspired parts of UUID v7 design