arizuko › reference › JID format

jid

Every chat and every sender is a JID of the form <platform>:<rest>. The first segment of <rest> is a kind discriminator. JIDs are plain strings; routing matches them with path.Match glob semantics across all routing keys.

1. Wire form & grammar

A JID is arizuko’s universal address for who and where — one string that works across Telegram, Discord, or the web, so routing rules never need per-platform logic.

jid      := platform ":" rest
platform := lowercase adapter name (everything before the first ":")
rest     := opaque platform-owned path (everything after the first ":")
kind     := first segment of rest before "/"

The platform/rest split is the only structure core enforces. Two helpers in core/types.go perform it:

• core.JidPlatform(jid) — everything before the first :; "" when there's no colon or the colon is at position 0.
• core.JidRoom(jid) — everything after the first :; the whole string when there's no colon.

2. Code shape

A JID is a string. Message.ChatJID and Message.Sender are both string fields on core.Message. There is no parse step, no net/url wrapper, and no separate chat-vs-sender Go type — the gateway never interprets <rest>, it only glob-matches the full string. Adapters own the per-platform shape of <rest> (section 3).

3. Per-platform schemas

Each adapter owns its <rest> shape. From specs/5/S-jid-format.md § "Per-platform schemas" plus the rewriter rules in 0042-typed-jids.sql:

Discord placeholder. Legacy rows with no stored guild_id migrated to discord:_/<channel> (placeholder kind). New inbound from discd carries the real guild ID. See 0042-typed-jids.sql:107.

Web is folder-keyed. The chat JID is the folder (with optional /<suffix>); the URL token is a separate row in route_tokens that maps to this JID. See route tokens and spec 5/W.

4. Routing & glob matching

The route table's match column is a space-separated list of key=glob predicates. Evaluation lives in router.RouteMatches; keys are extracted from the message via msgField:

Glob match uses Go's path.Match semantics:

• * matches any non-/ sequence (segments are first-class).
• ? matches exactly one non-/ char.
• [abc] / [a-z] matches a character class.
• \ escapes the next character.

From the RouteMatches contract (router.go:290-324):

Malformed tokens (no = or empty key) are skipped, not errored. The empty match expression matches everything.

The matcher is Go's path.Match applied directly to the JID string; router.RouteMatches is the only matcher. There is no separate core.MatchJID helper — a JID is a string, so path.Match(pattern, jid) is all a pattern check needs.

5. Examples

# all telegram groups
match='platform=telegram chat_jid=telegram:group/*'

# discord guild 67890, any channel/thread
match='chat_jid=discord:67890/*'

# all Discord DMs
match='chat_jid=discord:dm/*'

# all WhatsApp groups (server suffix discriminates)
match='chat_jid=whatsapp:*@g.us'

# all activity on a Mastodon instance (single account-id digit-or-letter)
match='chat_jid=mastodon:account/*'

# specific Telegram room by signed numeric ID (room=<rest after colon>)
match='platform=telegram room=group/-100123456'

# any non-message verb on any platform (join, edit, delete, …)
match='verb=*'
match='verb=' is the negation: only verb-less (default 'message') rows

6. Globs in grant rules

The same jid=<glob> syntax appears in grant rules (grants reference). The matcher there is grants.matchGlob with isValueDelim stopping * at , or ) — not at /. That's a deliberate difference: grant param globs span the whole JID, route globs are segment-aware.

send(jid=telegram:group/*)     # rule: only telegram groups (grants matcher: * spans /)
match='chat_jid=telegram:group/*'  # route: only telegram groups (path.Match: * doesn't cross /)

For top-level platform globs both forms agree (telegram:*/* in routes vs telegram:* in grants); both mean "anything telegram." For grant params there's only one trailing segment to match against, so the wider * is harmless.

7. Hard cutover & migration history

Migrations 0042-typed-jids.sql and 0043-typed-jids-tail.sql rewrote every JID-shaped value in the store to the typed form. Affected columns:

• messages.chat_jid, messages.sender, messages.reply_to_sender
• chats.jid (PK)
• onboarding.jid
• (pre-0053: user_jids.jid and vestigial grants.jid were rewritten too, before being dropped by the ACL unification)
• routes.match — chat_jid= / sender= / room= predicates
• scheduled_tasks.chat_jid
• chat_reply_state.jid

Every UPDATE is guarded by a NOT LIKE on the new shape, so re-running is idempotent. Rules:

• Telegram — signed integer split: positive → telegram:user/<id>, negative → telegram:group/<|id|> (sign dropped).
• Discord — split via chats.is_group: DMs → discord:dm/<channel>, guild channels → discord:_/<channel> (placeholder).
• Mastodon — drop host (single-instance per deployment); account/<id> for senders/recipients.
• Reddit — thing-prefix lookup: t1_→comment, t2_→user, t3_→submission.
• Bluesky — percent-encode the embedded : in did:plc:<rest> → bluesky:user/did%3Aplc%3A<rest>.
• Email — senders rewritten to email:address/<addr>; chat_jid rewrite deferred until emaid emits typed form.
• LinkedIn — <urn> → user/<urn>.
• WhatsApp + Twitter — already conformant; not touched.
• Web — web:<folder>[/<suffix>] remains folder-keyed; the URL token is decoupled into the route_tokens table (one row per URL, JID per row).
• Hook — new top-level platform hook:<folder>/<source>[/<suffix>] for webhook ingest via route_tokens; <folder> is the destination folder, sender on inbound is the <source> segment.
• Routes — bare platform:* globs rewritten to platform:*/* so segment-aware path.Match still matches anything on that platform.

8. Design discipline

• Kind in the path. The first segment after the colon discriminates resource kind on the wire. The role (chat vs sender) is which message field holds the string — ChatJID or Sender — not a distinct Go type.
• Adapter owns its schema. Core only splits <platform>:<rest> via JidPlatform/JidRoom. Each adapter constructs and parses <rest> per its own declared shape.
• URI-clean. Adapters percent-encode reserved chars in <rest> (a Bluesky DID's colons, for example) so the platform/rest split holds.
• One URL = one resource. No sign-bit hacks, no t1_/t2_/t3_ prefix soup, no in-band server suffixes for code (WhatsApp keeps @server because its existing shape already encodes kind).
• Adding a kind later is one string. A new platform kind earns its place when an adapter, the gateway, or the agent treats it differently from siblings. No system-wide format change, no DB migration of existing rows.

9. Go deeper

• core/types.go — JidPlatform, JidRoom, the Message struct (string ChatJID / Sender fields)
• router/router.go — RouteMatches, msgField, ResolveRoute
• specs/5/S-jid-format.md — full spec, per-platform schemas, design discipline
• grants reference — how jid=… appears in grant rule params
• schema reference — every column that stores a JID