Specification · Draft v1.0 · 2026-08-17
A 256-bit (32-byte), purely random unique identifier, formatted 16-8-8-8-24 — the standard UUID's 8-4-4-4-12 with every group doubled.
The 256-bit analogue of UUIDv4 — same idea, twice the random bits, same visual shape.
UUID256 is a fixed-size, globally unique, purely random identifier meant for use as a primary or unique key in databases, message systems, and APIs. It carries 250 bits of cryptographically random data (versus 122 for UUIDv4), so collisions are unreachable in practice at any generation rate, with no coordination, clocks, or node identifiers required. Nothing about when, where, or how fast an id was generated can be recovered from it — there is nothing embedded to leak.
The text format is deliberately kin to the standard UUID: every field of 8-4-4-4-12 is doubled to 16-8-8-8-24, so the version digit still opens the third group and the variant digit still opens the fourth — exactly where a UUID reader already expects them — while the extra length makes it impossible to mistake for a real 128-bit UUID.
32 bytes from the OS CSPRNG, then two bytes are touched to stamp version (4) and variant (10). Nothing else changes.
No clock, counter, or machine identity. Any number of generators — threads, processes, machines — run forever without coordinating.
Numeric order of the 256-bit value, byte order of the encoding, and code-point order of the canonical text are identical — but carry no meaning, since the value is uniform random.
Accepts the 68-char hyphenated canonical form or the 64-char compact form, any letter case; strict mode also checks version/variant.
BYTEA / BINARY(32) / BLOB preferred; CHAR(68) where text is required.
The normative spec lives in README.md — text format, binary layout, generation, parsing, storage, and test vectors.
All 39 implement the same API — generate, to_canonical, parse (strict/lenient), is_strict — and self-check against the spec's test vectors on start-up. Sources live flat in reference/; only sources are kept there. Build/run commands assume you're inside that directory.