chat/schema/README.md

Message Schemas

JSON Schema definitions (draft 2020-12) for the chat protocol. Messages use IRC command names and numeric reply codes (RFC 1459/2812) encoded as JSON over HTTP.

Envelope

Every message is a JSON object with a command field. The format maps directly to IRC wire format:

IRC:  :nick PRIVMSG #channel :hello world
JSON: {"command": "PRIVMSG", "from": "nick", "to": "#channel", "body": ["hello world"]}

IRC:  :server 353 nick = #channel :user1 @op1 +voice1
JSON: {"command": "353", "to": "nick", "params": ["=", "#channel"], "body": ["user1 @op1 +voice1"]}

Multiline:  {"command": "PRIVMSG", "to": "#ch", "body": ["line 1", "line 2"]}
Structured: {"command": "PUBKEY", "body": {"alg": "ed25519", "key": "base64..."}}

Common fields (see message.json for full schema):

Field	Type	Description
id	string (uuid)	Server-assigned message UUID
command	string	IRC command or 3-digit numeric code
from	string	Source nick or server name (IRC prefix)
to	string	Target: #channel or nick
params	string[]	Middle parameters (mainly for numerics)
body	array | object	Structured body — never a raw string (see below)
ts	string	ISO 8601 timestamp (server-assigned, not in raw IRC)
meta	object	Extensible metadata (signatures, hashes, etc.)

Structured bodies: body is always an array of strings (for text) or an object (for structured data like PUBKEY). Never a raw string. This enables:

• Multiline messages without escape sequences
• Deterministic canonicalization via RFC 8785 JCS for signing
• Structured data where needed

Commands

IRC commands used for client↔server and server↔server communication.

Command	File	RFC	Description
PRIVMSG	commands/PRIVMSG.json	1459 §4.4.1	Message to channel or user
NOTICE	commands/NOTICE.json	1459 §4.4.2	Notice (no auto-reply)
JOIN	commands/JOIN.json	1459 §4.2.1	Join a channel
PART	commands/PART.json	1459 §4.2.2	Leave a channel
QUIT	commands/QUIT.json	1459 §4.1.6	User disconnected
NICK	commands/NICK.json	1459 §4.1.2	Change nickname
TOPIC	commands/TOPIC.json	1459 §4.2.4	Get/set channel topic
MODE	commands/MODE.json	1459 §4.2.3	Set channel/user modes
KICK	commands/KICK.json	1459 §4.2.8	Kick user from channel
PING	commands/PING.json	1459 §4.6.2	Keepalive
PONG	commands/PONG.json	1459 §4.6.3	Keepalive response
PUBKEY	commands/PUBKEY.json	(extension)	Announce/relay signing key

Numeric Replies

Three-digit codes for server responses, per IRC convention.

Success / Informational (0xx–3xx)

Code	Name	File	Description
001	RPL_WELCOME	numerics/001.json	Welcome after session creation
002	RPL_YOURHOST	numerics/002.json	Server host info
003	RPL_CREATED	numerics/003.json	Server creation date
004	RPL_MYINFO	numerics/004.json	Server info and modes
322	RPL_LIST	numerics/322.json	Channel list entry
323	RPL_LISTEND	numerics/323.json	End of channel list
332	RPL_TOPIC	numerics/332.json	Channel topic
353	RPL_NAMREPLY	numerics/353.json	Channel member list
366	RPL_ENDOFNAMES	numerics/366.json	End of NAMES list
372	RPL_MOTD	numerics/372.json	MOTD line
375	RPL_MOTDSTART	numerics/375.json	Start of MOTD
376	RPL_ENDOFMOTD	numerics/376.json	End of MOTD

Errors (4xx)

Code	Name	File	Description
401	ERR_NOSUCHNICK	numerics/401.json	No such nick/channel
403	ERR_NOSUCHCHANNEL	numerics/403.json	No such channel
433	ERR_NICKNAMEINUSE	numerics/433.json	Nickname already in use
442	ERR_NOTONCHANNEL	numerics/442.json	Not on that channel
482	ERR_CHANOPRIVSNEEDED	numerics/482.json	Not channel operator

Federation (S2S)

Server-to-server messages use the same command format. Federated servers relay messages with an additional origin field in meta to track the source server. The PING/PONG commands serve as inter-server keepalives. State sync after link establishment uses a burst of JOIN, NICK, TOPIC, and MODE commands.