# 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.