Validador de UUID

Validação de UUID, versão por versão

Um UUID (Universally Unique Identifier) é um valor de 128 bits tipicamente escrito como 32 dígitos hexadecimais no padrão 8-4-4-4-12 — por exemplo f47ac10b-58cc-4372-a567-0e02b2c3d479 (36 caracteres com hífens). A referência canônica foi a RFC 4122 (2005); foi substituída e estendida pela RFC 9562 em 2024, que adicionou as versões 6, 7 e 8 sem quebrar as anteriores.

A validação estrutural é simples: uma única regex pega o padrão de dígitos, o nibble de versão e os bits de variante. O difícil é escolher a versão certa para cada caso.

/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i

O terceiro grupo começa com 1–8 — esse nibble é a versão. O quarto grupo precisa começar com 8, 9, a ou b — esses são os dois bits altos de variante (10x em binário) que marcam um UUID RFC 4122 / 9562. Strings que passam pelo formato de dígitos mas falham nessas duas posições são inválidas mesmo parecendo corretas.

As oito versões

• v1 — timestamp de 60 bits + MAC de 48 bits. Ordenável, mas vaza o MAC da máquina e o instante de criação.
• v3 — hash MD5 de um UUID de namespace mais um nome. Determinístico: a mesma entrada gera sempre o mesmo UUID.
• v4 — 122 bits de aleatoriedade pura. A versão mais comum, mas totalmente desordenada, o que causa fragmentação de índice B-tree.
• v5 — mesma ideia do v3, mas com SHA-1 no lugar de MD5. Preferível ao v3.
• v6 — v1 com os campos de timestamp reordenados para o UUID ordenar lexicograficamente por tempo.
• v7 — timestamp Unix em milissegundos (48 bits) + 74 bits de aleatoriedade. Recomendação moderna: ordenável, sem vazamento de MAC e amigável para índices.
• v8 — layout totalmente customizado, escape hatch para apps que precisam de codificação própria sem sair da RFC.

Valores especiais e casos extremos

O nil UUID 00000000-0000-0000-0000-000000000000 é reservado pelo spec para significar "sem valor" — tecnicamente é válido sintaticamente, mas não codifica versão alguma, então a maioria dos validadores sinaliza separadamente. O max UUID ffffffff-ffff-ffff-ffff-ffffffffffff foi padronizado pela RFC 9562 com função análoga. UUIDs são case-insensitive, mas o spec recomenda minúsculas; sistemas legados (GUIDs do Windows no registro, JWTs com jti) costumam emitir em maiúsculas. Algumas implementações também aceitam a forma sem hífens (32 dígitos hex contíguos), mas a forma canônica sempre inclui os quatro hífens.

Armazenamento, indexação e bibliotecas

O Postgres tem o tipo uuid nativo (16 bytes binários) mais as extensões uuid-ossp e pgcrypto para geração. O MySQL guarda como BINARY(16) — texto desperdiça. O ObjectId do MongoDB tem só 12 bytes, mas não é um UUID. No Node, o pacote npm uuid é canônico; nos navegadores modernos crypto.randomUUID() gera um v4 sem dependência alguma.

Perguntas frequentes

v4 ou v7 para projetos novos? v7 em quase todos os casos. Mantém a propriedade de não exigir coordenação do v4, ordena por instante de criação (então indexa bem em B-tree) e o prefixo em milissegundos permite ordenar eventos sem precisar de uma coluna created_at separada.

O nil UUID é válido? Sintaticamente sim, semanticamente significa "ausente" — trate igual a NULL no seu domínio.

O v1 realmente vaza o MAC? Sim. Os últimos 48 bits são o MAC da placa de rede do host mais o timestamp de criação. Por isso v1 não é recomendado para IDs públicos — permite que um atacante correlacione UUIDs gerados na mesma máquina.

UUID pode colidir? Matematicamente sim, na prática não. Para v4, seriam necessários 2,71 quintilhões de UUIDs antes da chance de uma colisão atingir 50% (limite do paradoxo do aniversário). A um milhão de UUIDs por segundo, daria 85 anos.