UUID Validation in Node.js — Versions, Variants, and Common Pitfalls

1. Why UUID validation matters

A Universally Unique Identifier (UUID) is a 128-bit label used to identify resources across systems without coordination. UUIDs appear as database primary keys (PostgreSQL's uuid type), distributed system node identifiers, message deduplication keys, and API idempotency tokens.

Accepting an invalid UUID can corrupt your data layer, cause silent lookup failures, or break downstream services that expect a specific version. In event-driven architectures, a malformed idempotency key can lead to duplicate processing or lost events.

2. UUID versions explained

Not all UUIDs are random. Each version encodes different information and is suited for different use cases:

3. The anatomy of a UUID

A UUID is displayed as 32 hexadecimal digits in the canonical 8-4-4-4-12 format, separated by hyphens:

4. Why regex isn't enough

The most common approach to UUID validation in Node.js is a regex like this:

// ❌ Matches the format but ignores version and variant
const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

This regex checks the shape of a UUID but misses critical semantic checks:

5. The right solution — IsValid API

The IsValid UUID API validates the format, detects the version (0-15) and variant (RFC 4122, NCS, Microsoft, or future), and optionally enforces a specific version — all in a single call.

Pass any string to the API and get back whether it is a valid UUID, which version it is, and which variant it uses. You can also filter by a specific version to reject UUIDs that don't match your requirements.

Full parameter reference and response schema: UUID API docs →

6. Node.js code example

Using the @isvalid-dev/sdk package or the native fetch API (Node 18+).

// validateUuid.js
import { createClient } from '@isvalid-dev/sdk';

const iv = createClient({ apiKey: process.env.ISVALID_API_KEY });

// ── Basic validation ─────────────────────────────────────────────────────────

const result = await iv.uuid('550e8400-e29b-41d4-a716-446655440000');

console.log(result.valid);   // true
console.log(result.version); // 4
console.log(result.variant); // 'rfc4122'

// ── Enforce a specific version ───────────────────────────────────────────────

const v7 = await iv.uuid('01932c07-209c-7f43-b572-6a8270527ca5', { version: 7 });

if (!v7.valid) {
  console.log('Not a valid v7 UUID');
}

// middleware/validateIdParam.js
export async function validateIdParam(req, res, next) {
  const { id } = req.params;
  if (!id) return next();

  try {
    const result = await iv.uuid(id, { version: 4 });
    if (!result.valid) {
      return res.status(400).json({
        error: 'Invalid resource ID',
        message: 'Expected a valid v4 UUID',
      });
    }
  } catch {
    // API unavailable — fall through to let the DB handle it
  }

  next();
}

7. cURL example

Validate a UUID from the command line:

curl -G -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "value=550e8400-e29b-41d4-a716-446655440000" \
  "https://api.isvalid.dev/v0/uuid"

Enforce a specific version (returns valid: false if the UUID is not v7):

curl -G -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "value=550e8400-e29b-41d4-a716-446655440000" \
  --data-urlencode "version=7" \
  "https://api.isvalid.dev/v0/uuid"

8. Understanding the response

Valid v4 UUID:

{
  "valid": true,
  "version": 4,
  "variant": "rfc4122"
}

Invalid UUID (wrong format):

{
  "valid": false,
  "version": null,
  "variant": null
}

9. Edge cases

const nil = await iv.uuid('00000000-0000-0000-0000-000000000000');
// { valid: true, version: 0, variant: 'ncs' }