Namespaces for name-based UUIDs

UUID text7 sectionsUpdated

A name-based UUID needs a namespace: a UUID that says which kind of name you are hashing. Four are registered (DNS, URL, OID and X.500), and any UUID of your own works just as well.

The namespace is what keeps the host name example.com and the URL https://example.com from colliding into one identifier. This page lists the registered four, explains what belongs in each, and covers rolling your own.

What the converter readscomputed by the converter itself
in6ba7b810-9dad-11d1-80b4-00c04fd430c8outuuid · RFC 9562 (10xx) · version 1

The DNS namespace

in6ba7b814-9dad-11d1-80b4-00c04fd430c8outuuid · RFC 9562 (10xx) · version 1

The X.500 namespace, differing in the 8th hex digit

Open the converter: UUID textNothing you paste leaves the browser.
On this page (7)

The four registered namespaces#

NamespaceIDWhat the name should be
DNS6ba7b810-9dad-11d1-80b4-00c04fd430c8A host name: example.com
URL6ba7b811-9dad-11d1-80b4-00c04fd430c8A URL: https://example.com/a
OID6ba7b812-9dad-11d1-80b4-00c04fd430c8An ISO OID: 1.3.6.1
X5006ba7b814-9dad-11d1-80b4-00c04fd430c8An X.500 distinguished name

They differ by a single hex digit, which is a common source of copy-paste bugs: DNS ends 810, URL 811, OID 812 and X.500 814. There is no 813.

All four are version 1 identifiers, and their clocks carry the same instant: 1998-02-04T22:13:53.151Z. They were generated in one sitting a quarter of a century ago and have not moved since, which is exactly what a namespace constant should do.

RFC 9562 § 6.6 · Namespace ID Usage and AllocationNamespace ID usage and allocation

RFC 9562 § 7.2 · IANA UUID Namespace ID Registry and RegistrationThe IANA registry the namespaces live in

Why a namespace exists at all#

Without it, every name-based identifier would live in one flat space, and two systems hashing unrelated strings would eventually agree by accident. The namespace prefixes the hash input, so example.com as a host and example.com as a tenant slug in your own namespace derive to different identifiers.

Defining your own#

Generate one v4, write it into a constant, and never change it. That constant is now the root of a private identifier space: v5 of it and a tenant slug is stable forever, and nobody else can land in your space by accident. Changing it later invalidates every identifier derived beneath it, so treat it like a schema, not like configuration.

javascript
import { v5 } from "uuid";

// generated once, then frozen
const TENANTS = "3f2b7e9a-9a2f-4a1a-9f37-1c4a2ee1f5b3";

const id = v5("acme", TENANTS);   // the same every time, everywhere

Nesting namespaces#

A derived UUID is a perfectly good namespace for the next level: v5 of your root and a tenant gives a tenant namespace, and v5 of that and a resource name gives a resource identifier. The chain stays deterministic all the way down, which is how content-addressed hierarchies get built without a registry.

RFC 9562 § 6.5 · Name-Based UUID GenerationWhat the standard requires of the derivation at every level

Questions people actually ask#

What are the four standard UUID namespaces?

DNS 6ba7b810-9dad-11d1-80b4-00c04fd430c8, URL …811…, OID …812… and X.500 …814…. They differ by one hex digit and there is no …813….

Can I invent my own namespace UUID?

Yes, any UUID works. Generate a v4 once, freeze it as a constant, and treat changing it as a breaking schema change.

Does the namespace need to be secret?

It cannot be. Namespaces are published constants, and a name-based UUID is guessable whenever the name is.

Browse the reference