---
title: Identity (TypeID)
description: How Dispatch uses prefix-qualified, globally unique identifiers for every entity.
---

Every entity in Dispatch has a TypeID. TypeIDs are globally unique, sortable, URL-safe identifiers built on UUIDv7 with a human-readable prefix that tells you what kind of entity you're looking at.

A TypeID looks like this:

```
job_01h455vb4pex5vsknk084sn02q
```

The `job` prefix identifies this as a job. The suffix is a base32-encoded UUIDv7 that encodes creation time, so IDs sort chronologically.

## The `id` package

The `id` package wraps the [TypeID Go library](https://github.com/jetify-com/typeid-go) (v2) with a single `ID` struct. All entity types share the same struct -- the prefix distinguishes them.

### Creating IDs

```go
import "github.com/xraph/dispatch/id"

jobID      := id.New(id.PrefixJob)        // job_01h455vb...
workflowID := id.New(id.PrefixWorkflow)   // wf_01h455vb...
runID      := id.New(id.PrefixRun)        // wfrun_01h455vb...
cronID     := id.New(id.PrefixCron)       // cron_01h455vb...
```

Convenience constructors: `id.NewJobID()`, `id.NewWorkflowID()`, `id.NewRunID()`, `id.NewCheckpointID()`, `id.NewCronID()`, `id.NewDLQID()`, `id.NewEventID()`, `id.NewWorkerID()`.

### Parsing IDs

```go
parsed, err := id.Parse("job_01h455vb4pex5vsknk084sn02q")
parsed, err := id.ParseWithPrefix("job_01h455vb...", id.PrefixJob)  // validates prefix
parsed, err := id.ParseJobID("job_01h455vb...")                     // convenience
```

### Nil ID

```go
var empty id.ID
empty.IsNil()  // true
empty.String() // ""
id.Nil.IsNil() // true
```

### Database storage

`id.ID` implements `Scanner` and `driver.Valuer`. Stores as a string, returns `NULL` for nil IDs.

### JSON serialization

`id.ID` implements `TextMarshaler` and `TextUnmarshaler`. Nil IDs serialize as empty strings.

## Prefix reference

| Constant | Prefix | Entity |
|----------|--------|--------|
| `id.PrefixJob` | `job` | Job |
| `id.PrefixWorkflow` | `wf` | Workflow |
| `id.PrefixRun` | `wfrun` | Workflow run |
| `id.PrefixCheckpoint` | `ckpt` | Checkpoint |
| `id.PrefixCron` | `cron` | Cron schedule |
| `id.PrefixDLQ` | `dlq` | Dead letter queue entry |
| `id.PrefixEvent` | `evt` | Event |
| `id.PrefixWorker` | `wkr` | Worker |