Implementing
View this section in the spec ↗TNID spec version 0, draft, as of 2026-09-28; libraries are pre-1.0. To use TNIDs rather than implement them, start with the Guide and a library.
The spec is canonical
| Source | Role |
|---|---|
| spec.md | Normative. Wins every disagreement. |
| These pages | Restate the spec with diagrams and worked examples. No requirements of their own; MUST, SHOULD and MAY (RFC 2119) appear only when repeating the spec. |
Rust tnid crate | Reference implementation; the test vectors come from it. Where it disagrees with the spec (Must reject), follow the spec. |
| Conformance checklist | Every requirement on one page. |
Conforming means the same bits, the same strings, and the same accept or reject decisions as the spec for every input.
- 01 Design goalsWhat TNIDs are designed for, and the trade-offs they make to get there.
- 02 Bit layoutThe 128-bit layout every TNID shares: name, UUIDv8 version and variant, TNID variant, and payload bits.
- 03 EncodingsThe two sort-preserving, URL-safe character encodings used in TNID strings.
- 04 VariantsThe four TNID variants selected by the 2 TNID variant bits: two defined, two reserved.
- 05 RepresentationsHow a TNID is written in UUID form, as a 128-bit integer, bytes, or a TNID string, and why they all sort the same way.
- 06 Optional extensionsOptional TNID extensions: V0/V1 encryption and blocklist filtering.
- 07 Conformance checklistEverything a TNID library has to get right, each item linked to the page that explains it.
- 08 Test vectorsKnown-good inputs and outputs, and inputs that must be rejected, for testing a TNID implementation.