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. The uuid npm package exposes the standard namespaces via v5.DNS, v5.URL, and v5.OID constants.

How namespaces work

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

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:

NamespaceUUIDUse
DNS6ba7b810-9dad-11d1-80b4-00c04fd430c8Domain names (e.g. "example.com")
URL6ba7b811-9dad-11d1-80b4-00c04fd430c8URLs (e.g. "https://example.com/page")
OID6ba7b812-9dad-11d1-80b4-00c04fd430c8ISO Object Identifiers
X.5006ba7b814-9dad-11d1-80b4-00c04fd430c8X.500 distinguished names

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:

They are not appropriate for:

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

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

Frequently asked questions

What is a UUID namespace used for?

A namespace is itself a UUID used as a scope when generating name-based UUIDs (v3 or v5). Hashing the same name in two different namespaces produces two different UUIDs, allowing the same string to produce distinct IDs in different contexts. RFC 9562 Appendix C defines standard namespaces for URLs, DNS names, OIDs and X.500 names.

Which UUID version should I use?

For database primary keys and event IDs, use v7 — its millisecond timestamp prefix keeps B-tree inserts sequential. For externally visible identifiers like URLs and tokens, use v4 — pure randomness with no timestamp leakage. v5 is the choice when you need a deterministic UUID derived from a name or URL.

What is a UUID namespace used for?

A UUID namespace scopes name-based UUID generation (v3 and v5). Hashing the same name in different namespaces produces different UUIDs, preventing collisions between unrelated systems that use the same names. RFC 9562 §6.5 defines four standard namespaces: DNS (6ba7b810-...), URL (6ba7b811-...), OID (6ba7b812-...), and X.500 DN (6ba7b814-...).

Can I create my own UUID namespace?

Yes. Generate any UUID v4 and use it as your namespace. As long as it is unique to your system, it will prevent collisions with other namespaces. The uuid npm package and Python's standard library uuid module both accept custom namespaces for v5() generation: uuid.v5(name, myNamespaceUUID).

What is the difference between UUID v3 and UUID v5 namespaces?

Both use the same namespace concept, but v3 hashes with MD5 and v5 uses SHA-1. RFC 9562 recommends v5 over v3 because MD5 is cryptographically broken. Both produce deterministic UUIDs — the same namespace and name always produce the same UUID, which is useful for content addressing and deduplication.