Decodificatore UUID

Struttura UUID

Un UUID (Universally Unique Identifier) è un valore a 128 bit rappresentato come 32 cifre esadecimali divise in cinque gruppi da trattini:

La versione e la variante sono i soli due campi garantiti di essere presenti in ogni UUID. Tutti gli altri campi dipendono dalla versione.

Il campo versione

Il nibble di versione è la prima cifra esadecimale del terzo gruppo (posizione 14 nella stringa completa). Identifica la versione UUID usata per generare l'identificatore.

const hex = uuid.replace(/-/g, '')
const version = parseInt(hex[12], 16)  // single hex digit → 1, 2, 3, 4, 5, 6, 7, or 8

La versione 7 (UUID v7) è la versione più recente ampiamente usata, introdotta in RFC 9562 (2024). Codifica un timestamp Unix in millisecondi nei bit più significativi per l'ordinabilità.

Il campo variante

La variante è codificata nei bit più significativi del primo byte del quarto gruppo. Identifica le convenzioni di layout e di ordinamento dei byte usate dall'UUID.

In pratica, quasi tutti gli UUID che si incontrano utilizzano la variante RFC 4122 / RFC 9562 (schema di bit 10xx xxxx, primo byte del quarto gruppo nell'intervallo 0x80–0xBF). Le varianti NCS, Microsoft COM e Reserved sono formati legacy raramente presenti nei sistemi moderni.

Riferimento versioni UUID

RFC 4122 ha definito le versioni 1-5. RFC 9562 (2024) ha aggiunto le versioni 6, 7 e 8:

Decodifica dei timestamp UUID v1

UUID v1 incorpora un timestamp gregoriano a 60 bit (intervalli di 100 nanosecondi dal 15 ottobre 1582) suddiviso su tre campi: time_low (bit 0-31), time_mid (bit 32-47) e time_hi (bit 48-59). Questo strumento li riassembla e li converte in una data UTC standard.

// UUID v1: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
//           ^^^^^^^^ ^^^^ ^^^^ ^^^^^ ^^^^^^^^^^^^
//           time-low  mid  hi  clk   node (MAC)
//                          ^
//                          version nibble (1)

const hex = '6ba7b8109dad11d180b400c04fd430c8'

const tLow = parseInt(hex.slice(0, 8),  16)  // 0x6ba7b810
const tMid = parseInt(hex.slice(8, 12), 16)  // 0x9dad
const tHi  = parseInt(hex.slice(13, 16), 16) // 0x1d1 (skip version nibble at index 12)

// Reconstruct 60-bit timestamp (100-ns intervals since Oct 15, 1582)
const t = (BigInt(tHi) << 48n) | (BigInt(tMid) << 32n) | BigInt(tLow)

// Subtract Gregorian offset (Oct 15, 1582 → Jan 1, 1970 in 100-ns units)
const GREGORIAN_OFFSET = 122192928000000000n
const unixMs = (t - GREGORIAN_OFFSET) / 10000n

console.log(new Date(Number(unixMs)).toISOString())
// → 1998-02-04T22:13:53.578Z

UUID v1 dovrebbe essere trattato come sensibile: l'indirizzo MAC incorporato e il timestamp preciso possono identificare sia la macchina generatrice che il tempo di generazione.

Decodifica dei timestamp UUID v7

UUID v7 incorpora un timestamp Unix a 48 bit in millisecondi nei primi 48 bit (primo gruppo + prime 4 cifre del secondo gruppo). Questo strumento legge quei bit e li converte in una data UTC con precisione in millisecondi.

// UUID v7: 018e4bc8-1000-7000-8000-000000000001
//           ^^^^^^^^^^^^
//           48-bit Unix ms timestamp

const hex = '018e4bc8100070008000000000000001'

// First 48 bits (12 hex chars) = Unix timestamp in milliseconds
const ms = parseInt(hex.slice(0, 12), 16)  // 0x018e4bc81000

console.log(new Date(ms).toISOString())
// → 2024-03-11T…Z

// Everything after byte 6 is random (except version/variant bits)

A differenza di UUID v1, il timestamp UUID v7 usa l'epoch Unix familiare (1 gennaio 1970) e non incorpora nessuna informazione sull'host. I 74 bit rimanenti sono casuali.

Come questo strumento rileva la versione e la variante UUID

Il decoder legge la posizione 14 (nibble di versione) e la posizione 19 (nibble di variante) della stringa UUID canonica. Non è necessario nessuno stato esterno o contesto — tutte le informazioni sono contenute nella stringa UUID.

// Detect UUID version from the 13th hex character (index 12)
function uuidVersion(uuid) {
  const clean = uuid.replace(/-/g, '')
  return parseInt(clean[12], 16)
}

uuidVersion('550e8400-e29b-41d4-a716-446655440000') // → 4
uuidVersion('018e4bc8-1000-7000-8000-000000000001') // → 7
uuidVersion('6ba7b810-9dad-11d1-80b4-00c04fd430c8') // → 1

// Detect variant from the 17th hex character (index 16, first char of 4th group)
function uuidVariant(uuid) {
  const clean = uuid.replace(/-/g, '')
  const b = parseInt(clean[16], 16)
  if ((b & 0x8) === 0)      return 'NCS'
  if ((b & 0xC) === 0x8)    return 'RFC 4122'
  if ((b & 0xE) === 0xC)    return 'Microsoft'
  return 'Reserved'
}

UUID speciali

UUID nil

L'UUID nil 00000000-0000-0000-0000-000000000000 è tutto zeri. È definito da RFC 4122 come valore sentinella che significa 'nessun UUID' — analogo a null. Non è un UUID generato valido.

UUID max

L'UUID max ffffffff-ffff-ffff-ffff-ffffffffffff è tutto uni (0xFF in ogni byte). Definito in RFC 9562, è il complemento dell'UUID nil e serve come valore sentinella massimo.

Domande Frequenti