Definition

Content addressing is a technique where a resource’s identifier is derived from its content or canonical name, rather than from a random value or auto-increment counter. In UUID-based systems, UUID v5 is the standard mechanism: it hashes a namespace UUID together with the resource’s name or canonical URL to produce a stable, repeatable UUID.

The defining property is idempotence: computing the UUID for a resource twice — or on two different machines — always gives the same result. This makes content addressing particularly useful for distributed systems where the same logical resource may be created independently in multiple places.

How UUID v5 content addressing works

UUID v5 applies SHA-1 to the concatenation of a 16-byte namespace UUID and the resource name (as UTF-8 bytes), then truncates the result to 128 bits and sets the version (5) and variant bits:

UUID v5 = truncate_128(SHA1(namespace_bytes || name_utf8))
          with version nibble = 0101 and variant bits = 10

Four standard namespaces are defined by RFC 9562:

NamespaceUUIDUse for
DNS6ba7b810-9dad-11d1-80b4-00c04fd430c8Domain names
URL6ba7b811-9dad-11d1-80b4-00c04fd430c8URLs
OID6ba7b812-9dad-11d1-80b4-00c04fd430c8ISO OIDs
X.5006ba7b814-9dad-11d1-80b4-00c04fd430c8Distinguished names

Using a standard namespace means any system that generates a v5 UUID for the same URL with the URL namespace will get the same UUID — full cross-language, cross-system interoperability.

Common use cases

Stable page or resource IDs

import { v5 as uuidv5 } from 'uuid';

// The UUID for a URL is always the same — use as a cache key
const pageId = uuidv5('https://myapp.com/products/widget-42', uuidv5.URL);
// Always: same deterministic UUID

// Redis cache keyed by UUID v5 — no UUID stored in the database is needed
const cached = await redis.get(`page:${pageId}`);
if (!cached) {
  const html = await render('/products/widget-42');
  await redis.set(`page:${pageId}`, html, 'EX', 3600);
}

Deduplication of distributed writes

Without content addressing, two services that independently create the same resource may insert duplicate rows:

// Without content addressing — two services race to insert the same product
// Result: two rows with different UUID v4 values for the same product URL
await db.query('INSERT INTO products (id, url) VALUES ($1, $2)', [uuidv4(), url]);
// Service B does the same — duplicate row with a different id

// With content addressing — deterministic UUID prevents duplicates
const MY_NS = 'f47ac10b-58cc-4372-a567-0e02b2c3d479'; // project-specific namespace
const productId = uuidv5(url, MY_NS);

await db.query(
  'INSERT INTO products (id, url) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING',
  [productId, url]
);
// Both services generate the same productId — one insert succeeds, the other is a no-op

Terraform and infrastructure IDs

Terraform’s built-in uuidv5() function uses content addressing for stable infrastructure IDs that do not require state:

locals {
  # Same UUID every plan/apply — idempotent even after state loss
  bucket_id = uuidv5("dns", "${var.app_name}.${var.environment}.storage.internal")
}

resource "aws_s3_bucket" "app" {
  bucket = "app-${local.bucket_id}"
}

Idempotent seed data

import uuid

# Stable test fixture UUIDs — no database seed file needed
SEED_NS = uuid.UUID('00000000-0000-0000-0000-000000000001')

def seed_user_id(email: str) -> uuid.UUID:
    return uuid.uuid5(SEED_NS, email)

# Same IDs every time migrations run
admin_id  = seed_user_id('admin@example.com')   # always the same
editor_id = seed_user_id('editor@example.com')  # always the same

conn.execute(
    'INSERT INTO users (id, email) VALUES (%s, %s) ON CONFLICT DO NOTHING',
    (str(admin_id), 'admin@example.com')
)

Content addressing vs random UUIDs

PropertyContent addressing (UUID v5)Random UUID (UUID v4/v7)
Same input → same IDYesNo
Globally unique without coordinationYes, within a namespaceYes (probabilistic)
Supports deduplicationYesOnly with external lookup
Time-orderedNoUUID v7 yes
Requires a known inputYesNo
Security-sensitive hashNo (SHA-1 truncated)Yes (CSPRNG)

Content addressing and random UUIDs solve different problems — they are not interchangeable. Use UUID v5 when the resource has a canonical name. Use UUID v7 when you need a new unique ID for each record and chronological ordering matters.

Private namespaces

For application-specific content addressing, generate a private namespace UUID once with UUID v4 and store it in your application config:

// Generate once and store in config — never regenerate
const MY_APP_NAMESPACE = 'b6c7d8e9-f0a1-4b2c-8d3e-9f0a1b2c3d4e';

// Sub-namespaces per resource type prevent cross-type collisions
const USER_NS   = uuidv5('users',    MY_APP_NAMESPACE);
const PRODUCT_NS = uuidv5('products', MY_APP_NAMESPACE);

const userId    = uuidv5('alice@example.com', USER_NS);
const productId = uuidv5('https://myapp.com/p/42', PRODUCT_NS);

Using sub-namespaces ensures that a user email and a product URL with the same string value cannot produce the same UUID.

External references

Frequently asked questions

What UUID version is used for content addressing?

UUID v5 is the standard choice. It hashes a namespace UUID and a name string with SHA-1 to produce a deterministic UUID — the same namespace and name always yield the same UUID, on any machine, in any language. UUID v3 uses MD5 and is functionally equivalent but deprecated in favour of v5. UUID v8 can also be used for custom deterministic schemes, but v5 is the interoperable standard defined in RFC 9562 §5.5.

How is content addressing different from using UUID v4?

UUID v4 is random — calling it twice for the same content produces two different UUIDs. Content addressing with UUID v5 is deterministic — calling it twice for the same content always produces the same UUID. This distinction is critical for deduplication: if two systems independently generate a v5 UUID from the same URL, they get the same UUID and can share cache entries, avoid duplicate database rows, and reconcile records without coordination.

Is UUID v5 cryptographically secure for content addressing?

UUID v5 uses SHA-1, which is not recommended for cryptographic security (collision attacks exist). For content addressing purposes — deriving a stable ID from a canonical name — SHA-1 is sufficient because the goal is not tamper-resistance but deterministic identity. If you need a cryptographically secure content fingerprint, use SHA-256 or BLAKE3 and store the hash separately. Do not use UUID v5 as a security-critical content hash.

Can two different names produce the same UUID v5 (content collision)?

Theoretically yes, because SHA-1 output is truncated to 122 usable bits. A practical SHA-1 collision requires enormous computational effort — currently estimated at 2⁶³ operations for a chosen-prefix attack. For content addressing of natural names (URLs, file paths, DNS names), the probability of an accidental collision is negligible. Use a database unique constraint on the UUID column to detect any collision if it matters for correctness.