Skip to content

Identity Model

Jump to bottom
AstorisTheBrave edited this page Aug 30, 2026 · 2 revisions

Identity model

MID <-> PID
REF -> storage -> MID

MID: machine identifier

The MID is the source of truth. It is an RFC 9562 UUIDv7 in canonical lowercase 8-4-4-4-12 form.

  • Store it in a native UUID or 16-byte database column when available.
  • Use it for primary and foreign keys.
  • Treat its embedded timestamp as observable metadata, not trusted event time.
  • Do not infer a namespace from a raw MID.

PID: public identifier

The PID follows TypeID specification v0.3:

<public-prefix>_<26-character TypeID suffix>

It carries exactly the same 128 UUID bits as the MID. Conversion in either direction is deterministic when the namespace is known. A prefix such as order gives API consumers and operators useful type context without creating a second database identity.

Published namespace meanings must never be reassigned.

REF: human reference

A REF does not encode the MID. Applications maintain the REF-to-MID relationship in storage and must cross an atomic allocation boundary before claiming a REF is unique.

Human-reference strategies

Random references use a cryptographically secure Crockford Base32 payload, canonical grouping, and a modulo-37 check symbol. Atomic unique insertion with bounded retry establishes allocation.

Sequential references use a fixed-width decimal sequence with an optional UTC calendar-year scope. A transactional allocator must advance the counter and bind the sequence to the supplied MID in the same transaction.

Parsing or normalizing a REF proves only its syntax and checksum. Resolution is a separate storage operation.

Core invariants

  • Every entity has exactly one MID.
  • A PID must decode to exactly the same MID bits.
  • A REF must never be a truncation or reversible encoding of the MID.
  • Random REF uniqueness is established by an atomic unique insertion with bounded retry.
  • Sequential REF uniqueness is established by a transactional allocator.
  • Retired namespace definitions remain available for historical parsing.
  • MID, PID, and REF values are identifiers, never credentials.

Typical lifecycle

  1. Generate or accept a valid UUIDv7 MID.
  2. Persist the entity under that MID.
  3. Derive a PID for public software boundaries.
  4. If people need a reference, allocate one through the configured storage boundary.
  5. Resolve incoming REFs through storage; parse incoming PIDs directly back to their MID.
  6. Apply authentication and authorization before returning entity data.

See the normative specification for the complete contract.

Identifold

Clone this wiki locally