UUID Generation

The uuid module generates, validates, inspects, parses, and formats UUIDs. In deterministic workflows, v1, v4, and v7 generation runs as a recorded side effect and returns the recorded value during replay. Namespace-based v3 and v5 generation is deterministic and runs directly.

This page is an API reference of isolated calls. Values such as namespace, name, input, and id come from the surrounding application. Capture and handle the second error return before consuming generated, parsed, inspected, or formatted results. UUIDs are identifiers, not bearer credentials; do not use any UUID version as an authentication token or secret.

Loading

local uuid = require("uuid")

Nondeterministic UUIDs

Version 1

Time-based UUID with timestamp and node ID.

Version 1 exposes its creation time and node identifier. Avoid it where those details are sensitive; prefer v4 when only an opaque identifier is needed.

local id, err = uuid.v1()

Returns: string, error

Version 4

Random UUID.

local id, err = uuid.v4()

Returns: string, error

Version 7

A time-ordered UUID that encodes its creation time for chronological indexing. Do not rely on it as a strictly monotonic sequence, especially for values generated within the same timestamp interval.

local id, err = uuid.v7()

Returns: string, error

Deterministic UUIDs

Version 3

Deterministic UUID from namespace and name using MD5.

local id, err = uuid.v3(namespace, name)

Returns: string, error

Version 5

Deterministic UUID from namespace and name using SHA-1.

local NS_URL = "6ba7b811-9dad-11d1-80b4-00c04fd430c8"
local id, err = uuid.v5(NS_URL, "https://example.com/resource")
if err then
    return nil, err
end

Returns: string, error

Inspection

validate

local valid = uuid.validate(input)

Returns: boolean, nil. Non-string and malformed inputs return false; validation does not raise a structured error.

version

local ver, err = uuid.version(id)

Returns: integer, error

variant

local var, err = uuid.variant(id)

Returns: string, error (RFC4122, Reserved, Microsoft, Future, NCS, or Invalid)

parse

local info, err = uuid.parse(id)

Returns: table, error

Returned table fields:

• version (integer): UUID version (1, 3, 4, 5, or 7)
• variant (string): RFC4122, Reserved, Microsoft, Future, NCS, or Invalid
• timestamp (integer): Unix timestamp (v1 and v7 only)
• node (string): 6 raw node ID bytes (v1 only)

format

local formatted, err = uuid.format(id, "standard")
local formatted, err = uuid.format(id, "simple")
local formatted, err = uuid.format(id, "urn")

Returns: string, error

Errors

See Error Handling for working with errors.