UUID v5 Namespace: Complete Guide

How UUID v5 Works

UUID v5 is a "deterministic UUID": given the same namespace and name, it always produces exactly the same UUID. The generation process: concatenate the namespace UUID (16 bytes) and name (arbitrary byte sequence); compute SHA-1 hash of the concatenated result (160 bits); take the first 128 bits, set version field to 5, set variant field to RFC 4122; obtain the final UUID v5. The essence of UUID v5 is a specially formatted SHA-1 hash, so its "uniqueness" depends on namespace selection and SHA-1's collision resistance.

Standard Namespaces

RFC 4122 predefines 4 standard namespaces for generating UUIDs from different types of names:

• NAMESPACE_DNS (6ba7b810-9dad-11d1-80b4-00c04fd430c8): for DNS domain names, e.g., "example.com" → UUID
• NAMESPACE_URL (6ba7b811-9dad-11d1-80b4-00c04fd430c8): for URLs, e.g., "https://example.com/page" → UUID
• NAMESPACE_OID (6ba7b812-9dad-11d1-80b4-00c04fd430c8): for ISO OIDs (object identifiers)
• NAMESPACE_X500 (6ba7b814-9dad-11d1-80b4-00c04fd430c8): for X.500 directory names

You can also use custom namespaces: use any UUID v4 (randomly generated) as a private namespace UUID for your application or service; different applications using different namespaces will produce different UUIDs even for the same name.

Practical Use Cases for UUID v5

The core value of UUID v5 is "idempotency" — same input always produces the same ID. Common use cases: content-addressable storage (generating stable UUIDs for the same document's URL, facilitating deduplication); data synchronization (when syncing data from external systems, generating UUIDs from external IDs ensures idempotency); test data (generating reproducible test UUIDs for stable, repeatable tests); configuration files (generating deterministic UUIDs for config items without relying on database auto-increment IDs); event sourcing (generating deterministic event IDs for specific event types and parameters).

Multi-Language Code Examples

# Python
import uuid

# 使用标准命名空间
dns_uuid = uuid.uuid5(uuid.NAMESPACE_DNS, 'example.com')
url_uuid = uuid.uuid5(uuid.NAMESPACE_URL, 'https://example.com/page')
print(dns_uuid)  # 总是：cfbff0d1-9375-5685-968c-48ce8b15ae17

# 自定义命名空间（先生成一个固定的 v4 作为命名空间）
MY_APP_NAMESPACE = uuid.UUID('12345678-1234-5678-1234-567812345678')
user_id = uuid.uuid5(MY_APP_NAMESPACE, '[email protected]')
print(user_id)  # 对于相同邮箱总是产生相同 UUID

# JavaScript (uuid 包)
import { v5 as uuidv5, v4 as uuidv4 } from 'uuid';

const DNS_NAMESPACE = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
const id = uuidv5('example.com', DNS_NAMESPACE);
console.log(id); // cfbff0d1-9375-5685-968c-48ce8b15ae17

// 自定义命名空间
const MY_NAMESPACE = uuidv4(); // 应用启动时生成一次并保存
const userId = uuidv5('[email protected]', MY_NAMESPACE);

// Go
import (
    "github.com/google/uuid"
    "fmt"
)
id := uuid.NewSHA1(uuid.NamespaceDNS, []byte("example.com"))
fmt.Println(id)

UUID v3 vs v5: How to Choose

The only difference between UUID v3 and v5 is the hash algorithm: v3 uses MD5, v5 uses SHA-1. Functionally identical, both are deterministic namespace UUIDs. Selection guidance: prefer v5 (SHA-1), because MD5 is considered cryptographically insecure (even though here it's just used for generating deterministic IDs rather than security purposes, using a safer algorithm by default is good practice); if existing systems already use v3 and compatibility must be maintained, continue with v3; if two systems need to generate the same UUID (interoperability), they must use the same version (v3 or v5) and the same namespace.

Best Practices for Designing Application-Private Namespaces

Recommendations for designing application-private namespaces: each application or service uses a fixed random UUID v4 as namespace, hardcoded in configuration files or code constants (don't randomly generate each run); different entity types (users, articles, orders) use different sub-namespaces (can be derived with v5: derive a "users" namespace within the main namespace, then derive each user's UUID within the "users" namespace); the namespace UUID should be a secret application configuration — don't output in logs or expose in APIs; document your namespace UUIDs and naming conventions for each entity type so team members can reproduce the same UUIDs.