UUID Namespace

Definition

A UUID namespace is a UUID used as an input parameter when generating name-based UUIDs (versions 3 and 5). The namespace scopes the name: hashing the same string in two different namespaces produces two completely different UUIDs.

Namespaces allow independent systems to derive stable, deterministic UUIDs from the same names without colliding. For example, the string "example.com" hashed in the DNS namespace produces one UUID; hashed in the URL namespace it produces a different one.

How namespaces work

UUID v3 and v5 are generated by hashing a namespace UUID combined with a name string:

• v3 uses MD5
• v5 uses SHA-1 (preferred for new work — SHA-1 is stronger than MD5 for this purpose)

uuid_v5 = sha1(namespace_bytes + name_bytes)
         → truncate to 128 bits
         → set version bits to 5
         → set variant bits to RFC 9562

The namespace UUID is just bytes — it is concatenated with the name before hashing. This means the namespace acts as a domain separator.

Standard namespaces defined by RFC 9562

RFC 9562 defines four standard namespaces:

Use the DNS namespace for domain names and the URL namespace for full URLs. For anything else, either pick the closest standard namespace or define your own.

Defining a custom namespace

You can use any UUID as a namespace — including a randomly generated v4 UUID. The only requirement is that the namespace UUID is agreed upon by all parties who need to produce the same output.

A common pattern is to generate one v4 UUID per application or service and hard-code it as the namespace for all name-based UUIDs that service produces:

import { v5 as uuidv5 } from 'uuid';

// Generated once with crypto.randomUUID() — fixed for the lifetime of the app
const APP_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341';

function userIdFromEmail(email: string): string {
  return uuidv5(email, APP_NAMESPACE);
}

// Always returns the same UUID for the same email
userIdFromEmail('alice@example.com');
// → 'f47ac10b-58cc-5372-a567-0e02b2c3d479' (illustrative)

When to use name-based UUIDs

Name-based UUIDs (v5) are appropriate when:

• You need a deterministic identifier for a known input (URL, email, product SKU)
• Two independent systems need to independently arrive at the same UUID for the same thing
• You want to avoid storing a mapping table between names and IDs

They are not appropriate for:

• Primary keys for new records (use v7)
• Externally visible identifiers where the input name is sensitive (the hash is not a secret)
• Any situation where the input is not stable (a mutable field)

Python example

import uuid

DNS_NAMESPACE = uuid.NAMESPACE_DNS
url = uuid.uuid5(uuid.NAMESPACE_URL, "https://example.com")
print(url)  # deterministic, same every time

JavaScript example

import { v5 as uuidv5 } from 'uuid';

const id = uuidv5('https://example.com', uuidv5.URL);
// same input → same output, always

Related terms

• UUID — the base identifier used as input and output
• Variant — the bit field preserved in the generated UUID
• Collision — why two different names in the same namespace will not produce the same UUID

For random or time-based IDs, use the UUID v7 generator or UUID v4 generator.