UUID Version Detector

Identifying the UUID version: the single hex digit that tells you everything

When you receive a UUID over the wire — in a JSON body, a database row, a URL path — the first thing you usually need to know is which version generated it. The version is not a separate field; it is encoded inside the UUID itself, in a single hex digit at a fixed position. Once you can read that digit, you know whether you can extract a timestamp from it, whether it leaks a MAC address, whether it is sortable, and whether your parsing code is going to crash on a layout it does not expect.

This validator is narrower than a generic UUID checker (validador-uuid): instead of just saying "valid or not", it tells you which of the eight versions the input belongs to, so dispatching downstream logic becomes trivial.

UUID anatomy: where the version lives

A canonical UUID is 36 characters in the 8-4-4-4-12 pattern: xxxxxxxx-xxxx-Vxxx-vxxx-xxxxxxxxxxxx. The two characters that carry meaning are position 14 (the first character after the second hyphen — the V above) and position 19 (the first after the third hyphen — the v above):

• Position 14 — version nibble: a hex digit 1 through 8, telling you which RFC layout was used.
• Position 19 — variant nibble: must be 8, 9, A or B for the RFC 4122 / 9562 variant — the binary high bits are 10x. About 96.875% of generated UUIDs fall in this variant; the remaining 3.125% are reserved for legacy NCS, Microsoft GUID and future use.

Read in JavaScript, the version is one line:

function uuidVersion(uuid) {
  // index 14 in 0-based string indexing
  return parseInt(uuid.charAt(14), 16)
}

uuidVersion('f47ac10b-58cc-4372-a567-0e02b2c3d479') // 4
uuidVersion('017f22e2-79b0-7cc3-98c4-dc0c0c07398f') // 7

What each version digit means

• 1xxxxxxx → v1 — 60-bit timestamp (100 ns ticks since 1582-10-15) + 14-bit clock sequence + 48-bit MAC address. Sortable but leaks the host's MAC.
• 2xxxxxxx → v2 — DCE Security version. Reserved; almost never seen in modern systems.
• 3xxxxxxx → v3 — MD5 hash of a namespace UUID and a name. Deterministic.
• 4xxxxxxx → v4 — 122 bits of pure randomness. Most common version historically; not sortable.
• 5xxxxxxx → v5 — same as v3 but SHA-1. Preferred over v3 for security.
• 6xxxxxxx → v6 — v1 with the timestamp fields reordered so the UUID sorts lexicographically by time.
• 7xxxxxxx → v7 — 48-bit Unix millisecond timestamp + 74 random bits. The 2024 RFC 9562 recommendation for new systems.
• 8xxxxxxx → v8 — fully custom layout for applications that need their own encoding while staying RFC-compliant.

Special values: Nil UUID and Max UUID

Two strings exist outside the version scheme:

• Nil UUID — 00000000-0000-0000-0000-000000000000. Defined by RFC 4122 as "no value", used as a sentinel meaning NULL. Has no version digit (position 14 is 0, which is reserved).
• Max UUID — ffffffff-ffff-ffff-ffff-ffffffffffff. Added by RFC 9562 (2024) for the same role at the other end of the value space. Position 14 is f, which is also outside the 1-8 version range.

A version detector should return a special marker for these — not crash, not lie that they are valid v4. Both versions of the uuid npm package expose NIL and MAX constants and validate(uuid) / version(uuid) helpers that handle them.

Why version detection matters: dispatching parser logic

Different UUID versions carry different payloads, so version dispatch is essential when you want to extract metadata:

function timestampFromUuid(uuid) {
  switch (uuidVersion(uuid)) {
    case 1: return v1Timestamp(uuid)  // 100 ns since 1582
    case 6: return v6Timestamp(uuid)  // same epoch, reordered
    case 7: return v7Timestamp(uuid)  // Unix ms — easy
    default: return null              // v3/v4/v5/v8 have no timestamp
  }
}

The classic anti-pattern is assuming every UUID is v4 and feeding it to a random-only parser — code that worked for years suddenly crashes the day someone enables v7 in the application or a third-party integration ships a v1. Always branch on the version digit explicitly, or use a library that does it for you.

Brazilian context: migrating to v7 for database indexing

Brazilian engineering teams that started on Rails or Django with v4 UUIDs are now migrating to v7 specifically because of B-tree index fragmentation. Random v4 inserts spread across the index tree and force constant page splits; v7 inserts arrive in time order and fall at the end of the rightmost leaf, just like an auto-incrementing integer. The cutover is a one-liner change in the generation library (crypto.randomUUID() → uuidv7()) and is fully backward-compatible — the new ones validate as well-formed UUIDs everywhere.

FAQ

How exactly do I identify the version? Read character at index 14 in the 36-character string (the first character after the second hyphen). Parse as hex — that integer 1 through 8 is the version. Position 14 is one-based for humans, zero-based for programmers; the spec calls it the "version" nibble inside the third group.

Is v4 still the most common version? Historically yes, because crypto.randomUUID() in browsers and most stdlib helpers default to v4. v7 is catching up fast since RFC 9562 in 2024 — new Rails apps, Postgres extensions and ORMs are switching by default.

Will v7 replace v4? Gradually. For new tables, v7 is the better default (sortable, indexes well, no MAC leak). v4 keeps its place when you need maximum unguessability for public-facing IDs and do not care about insert order.

What does the Nil UUID mean? It is the reserved zero value, meaning "absent" — the spec recommends treating it like NULL. It has no version because position 14 is 0, which is outside the 1-8 version range.

Why is the variant 96.875%? The variant uses the two high bits of position 19 (the nibble after the third hyphen). The pattern 10x means the high bit is 1 and the next is 0, leaving the third bit free — that is 4 of the 16 possible hex digits (8, 9, A, B). 4/16 = 25%? No: the variant is defined by the top two bits, so 8/A/9/B all satisfy "top bit = 1, second bit = 0", which is 4 of the 8 high-bit-set values. The 96.875% figure comes from how much of the variant space (not the digit space) belongs to RFC 4122/9562.