TypeID

A type-safe, K-sortable, globally unique identifier inspired by Stripe IDs

What is it?

TypeIDs are a modern, type-safe extension of UUIDv7. Inspired by a similar use of prefixes in Stripe's APIs.

TypeIDs are canonically encoded as lowercase strings consisting of three parts:

1. A type prefix (at most 63 characters in all lowercase snake_case ASCII [a-z_]).
2. An underscore '_' separator
3. A 128-bit UUIDv7 encoded as a 26-character string using a modified base32 encoding.

Here's an example of a TypeID of type user:

  user_2x4y6z8a0b1c2d3e4f5g6h7j8k
  └──┘ └────────────────────────┘
  type    uuid suffix (base32)

A formal specification defines the encoding in more detail.

Benefits

• Type-safe: you can't accidentally use a user ID where a post ID is expected. When debugging, you can immediately understand what type of entity a TypeID refers to thanks to the type prefix.
• Compatible with UUIDs: TypeIDs are a superset of UUIDs. They are based on the upcoming UUIDv7 standard. If you decode the TypeID and remove the type information, you get a valid UUIDv7.
• K-Sortable: TypeIDs are K-sortable and can be used as the primary key in a database while ensuring good locality. Compare to entirely random global ids, like UUIDv4, that generally suffer from poor database locality.
• Thoughtful encoding: the base32 encoding is URL safe, case-insensitive, avoids ambiguous characters, can be selected for copy-pasting by double-clicking, and is a more compact encoding than the traditional hex encoding used by UUIDs (26 characters vs 36 characters).

Implementations

Implementations should adhere to the formal specification.

Latest spec version: v0.3.0

Official Implementations by jetify

Language	Status	Spec Version
Go	✓ Implemented	v0.3
SQL	✓ Implemented	v0.2
TypeScript	✓ Implemented	v0.3

Community Provided Implementations

Language	Author	Spec Version
C# (.Net)	@TenCoKaciStromy	v0.2 on 2023-06-30
C# (.Net Standard 2.1)	@cbuctok	v0.2 on 2023-07-03
C# (.NET)	@firenero	v0.3 on 2024-04-15
Dart	@mistermoe @tbd54566975	v0.2 on 2024-03-25
Elixir	@sloanelybutsurely	v0.3 on 2024-04-22
Haskell	@MMZK1526	v0.3 on 2024-04-19
Java	@fxlae	v0.3 on 2024-04-14
Java	@softprops	v0.2 on 2023-07-04
OCaml	@titouancreach	v0.3 on 2024-04-22
PHP	@BombenProdukt	v0.2 on 2023-07-03
Python	@akhundMurad	v0.2 on 2023-06-30
Ruby	@broothie	v0.3 on 2024-04-13
Rust	@conradludgate	v0.3 on 2023-04-12
Rust	@johnnynotsolucky	v0.2 on 2023-07-13
Scala	@ant8e	v0.3 on 2024-04-19
Scala	@guizmaii	Not validated yet
Swift	@Frizlab	v0.3 on 2024-04-19
T-SQL	@uniteeio	v0.2 on 2023-08-25
TypeScript	@ongteckwu	v0.2 on 2023-06-30
Zig	@tensorush	v0.2 on 2023-07-05

We are looking for community contributions to implement TypeIDs in other languages.

Command-line Tool

This repo includes a command-line tool for generating TypeIDs. To install it, run:

curl -fsSL https://get.jetify.com/typeid | bash

To generate a new TypeID, run:

$ typeid new prefix
prefix_01h2xcejqtf2nbrexx3vqjhp41

To decode an existing TypeID into a UUID run:

$ typeid decode prefix_01h2xcejqtf2nbrexx3vqjhp41
type: prefix
uuid: 0188bac7-4afa-78aa-bc3b-bd1eef28d881

And to encode an existing UUID into a TypeID run:

$ typeid encode prefix 0188bac7-4afa-78aa-bc3b-bd1eef28d881
prefix_01h2xcejqtf2nbrexx3vqjhp41

Related Work

• UUIDv7 - The upcoming UUID standard that TypeIDs are based on.

Alternatives to UUIDv7 that are also worth considering (but not type-safe like TypeIDs):

• xid
• ulid
• ksuid