API and Errors

API and errors

Unified operations

The full reference API defines five operations:

Operation	Purpose
create(namespace)	Create a MID/PID and cross any configured REF allocation boundary
parse(value)	Classify and parse one identifier representation
validate(value)	Return validity without claiming storage existence
inspect(value)	Return structured syntax, namespace, checksum, and resolution information
normalize(value)	Return the canonical representation for accepted input

The language ports expose the stable wire-level primitives using idiomatic naming. All implementations support MID parsing, MID/PID conversion, PID parsing, REF checksum behavior, random REF candidate formatting, sequential REF formatting, and normalization.

Parsing versus resolution

Parsing is syntactic. It answers questions such as:

• Is this a UUIDv7 MID?
• Is this a canonical TypeID-compatible PID?
• Does this REF match a registered format and checksum?

Resolution is stateful. It answers whether a valid REF is actually allocated and which MID it names. Implementations must not report a REF as resolved unless a resolver was explicitly invoked.

Namespace registry

A registry binds each public PID prefix to zero or one REF definition. The complete registry must be validated before use:

• public prefixes are unique;
• REF prefixes are unique case-insensitively;
• REF prefixes are prefix-free, preventing ambiguous hyphenless input; and
• published meanings are never reassigned.

Stable errors

Conforming implementations expose machine-readable error codes even when their human messages differ:

Code	Meaning
invalid_kind	Input cannot be classified as MID, PID, or REF
invalid_allocation_policy	Allocation configuration is inconsistent
invalid_mid	MID syntax or variant is invalid
invalid_uuid_version	UUID is not version 7
invalid_pid	PID suffix or canonical form is invalid
invalid_public_prefix	TypeID public prefix is malformed
unknown_namespace	Prefix is valid but not registered
invalid_ref	REF syntax is malformed
invalid_ref_prefix	REF prefix is malformed
ambiguous_ref_prefix	Registry prefixes would parse ambiguously
invalid_ref_length	REF payload length is incorrect
invalid_ref_symbol	REF contains a disallowed symbol
invalid_checksum	REF check symbol does not match
allocation_required	A storage boundary is required but absent
allocation_conflict	Atomic reservation encountered a unique conflict
allocation_exhausted	Bounded retry could not allocate a REF
sequence_overflow	Fixed-width sequence space is exhausted

Error classifications are part of the compatibility contract. Do not branch on language-specific message prose.

Canonical normalization

• MIDs normalize to lowercase canonical UUID text.
• PIDs use lowercase canonical TypeID encoding.
• REFs normalize to uppercase with canonical grouping.
• REF payload aliases accept O as 0 and I or L as 1 where the specification permits.

See the stable specification for normative behavior.