schema/README.md

@@ -20,7 +20,7 @@ are the fields it can have:
 - `code`: the number of a numeric reply, such as `1` for `RPL_WELCOME`. Absent
   on other messages.
 - `id`: the message's UUID, a unique ID that the server assigns.
-- `from`: the sender's nick, or the server name on a server message.
+- `from`: the sender's nick, or the server name on a numeric reply or a `PONG`.
 - `to`: the target, such as a channel name starting with `#` or a nick.
 - `params`: an array of strings with the message's other parameters, in order.
   `KICK` events and many numeric replies have it. The HTTP API ignores `params`
@@ -60,29 +60,32 @@ A `PRIVMSG` whose `body` has two strings is a two-line message:
 
 ## Files
 
+Most command files describe both the message a client sends and the message the
+server sends. Their field descriptions say where the two differ. The examples in
+the files leave out `id`, `ts` and `meta`.
+
 Commands, in `commands/`:
 
 - `PRIVMSG.json`: a message to a channel or a user.
 - `NOTICE.json`: a notice, which is a message that a client must not answer
   automatically.
-- `JOIN.json`: a user joined a channel.
-- `PART.json`: a user left a channel.
-- `QUIT.json`: a user left the server.
-- `NICK.json`: a user changed nick.
-- `TOPIC.json`: a channel topic was set.
-- `MODE.json`: a channel mode was changed.
-- `KICK.json`: a channel operator removed a user from a channel.
+- `JOIN.json`: joining a channel.
+- `PART.json`: leaving a channel.
+- `QUIT.json`: leaving the server.
+- `NICK.json`: changing nick.
+- `TOPIC.json`: setting a channel's topic.
+- `MODE.json`: querying or changing a channel's modes or the user's own modes.
+- `KICK.json`: a channel operator removing a user from a channel.
 - `PING.json`: a check that the server still answers.
-- `PONG.json`: the answer to a `PING`.
-- `PUBKEY.json`: an announcement of a user's public signing key. The server has
-  no such command. It answers a `PUBKEY` with `ERR_UNKNOWNCOMMAND` (`421`).
+- `PONG.json`: the answer to a `PING`, which is the HTTP response to it.
 
 Numeric replies, in `numerics/`:
 
-- `001.json`: `RPL_WELCOME`, which welcomes a new user.
+- `001.json`: `RPL_WELCOME`, which welcomes the user.
 - `002.json`: `RPL_YOURHOST`, the server's name and version.
-- `003.json`: `RPL_CREATED`, which says when the server was created.
-- `004.json`: `RPL_MYINFO`, the server's version and its lists of modes.
+- `003.json`: `RPL_CREATED`, the date the server last started.
+- `004.json`: `RPL_MYINFO`, the server's name, its version and its lists of
+  modes.
 - `322.json`: `RPL_LIST`, one channel in the answer to `LIST`.
 - `323.json`: `RPL_LISTEND`, the end of the answer to `LIST`.
 - `332.json`: `RPL_TOPIC`, a channel's topic.
@@ -96,71 +99,3 @@ Numeric replies, in `numerics/`:
 - `433.json`: `ERR_NICKNAMEINUSE`, the nick is taken.
 - `442.json`: `ERR_NOTONCHANNEL`, the user is not on that channel.
 - `482.json`: `ERR_CHANOPRIVSNEEDED`, the user is not a channel operator.
-
-## Where the files differ from the HTTP API
-
-Where a schema file and the HTTP API disagree, the HTTP API is right:
-
-- `message.json` and the files in `numerics/` put the three-digit code in
-  `command`. They have no `code` field. The HTTP API puts the reply's name in
-  `command` and its number in `code`.
-- `message.json` allows an object as `body`. The HTTP API reads only arrays of
-  strings. A `PRIVMSG` with an object as `body` gets `ERR_NOTEXTTOSEND` (`412`).
-- `message.json` says `to` is a channel or a nick. A `WALLOPS` message has `*`
-  there.
-- `message.json` allows `meta` on every message. The HTTP API keeps a client's
-  `meta` only on a `PRIVMSG` or `NOTICE`.
-- `message.json` describes signature fields in `meta`. The server never checks a
-  signature.
-- `message.json` does not describe `meta.hashcash`. The HTTP API reads it in a
-  `PRIVMSG` to a channel with mode `+H`.
-- `JOIN.json` has no `body`. A client's `JOIN` can carry the channel key in
-  `body`. When a user joins, the `JOIN` event repeats the channel name in
-  `body`.
-- `JOIN.json` allows a channel name of any length. The server allows at most 63
-  characters after the `#`. It answers a longer name with `ERR_NOSUCHCHANNEL`
-  (`403`).
-- `KICK.json` puts the kicked nick in `params`. The HTTP API reads a client's
-  `KICK` from `body`: the nick, then an optional reason.
-- `MODE.json` puts the mode change in `params`. The HTTP API uses `body`
-  instead. A client sends the change and any value as separate strings, such as
-  `"+o"` and `"bob"`. In a `MODE` event, `body` holds the change as one string,
-  such as `"+o bob"`, or as two strings, such as `"+k"` and `"secret"`.
-- `NOTICE.json` allows `*` as `to`. The server answers a `NOTICE` to `*` with
-  `ERR_NOSUCHNICK` (`401`).
-- `NOTICE.json` has an example notice from the server to `*`. The server sends
-  no such notice.
-- `PING.json` and `PONG.json` describe a token that the `PONG` repeats. The HTTP
-  API ignores the `body` of a `PING`. Its answer is the HTTP response
-  `{"command": "PONG", "from": "<server name>"}`.
-- `PING.json` and `PONG.json` also describe messages between servers. The server
-  does not connect to other IRC servers.
-- `PUBKEY.json` describes a command the server does not have.
-- `QUIT.json` says that `QUIT` comes only from the server. A client can send it
-  too, to end its session. A client's `QUIT` can carry a reason in `body`.
-- `TOPIC.json` says a `TOPIC` without a `body` queries the topic. The HTTP API
-  answers such a `TOPIC` with `ERR_NEEDMOREPARAMS` (`461`).
-- `TOPIC.json` says an empty array clears the topic. The HTTP API answers `[]`
-  with `ERR_NEEDMOREPARAMS` (`461`). A `body` of `[""]` clears the topic.
-- `003.json` describes the server's creation date. The HTTP API sends the date
-  the server last started.
-- `004.json` has example mode lists. The HTTP API sends `ow` as the user modes
-  and `Hbiklmnostv` as the channel modes.
-- `322.json` says `LIST` gets one reply per channel. The server leaves out a
-  secret channel, one with mode `+s`, unless the user is on it.
-- `332.json` says `RPL_TOPIC` answers a `TOPIC` query. The HTTP API has no such
-  query. It sends `RPL_TOPIC` after a client sets the topic, and after a `JOIN`
-  to a channel that has one.
-- `353.json` says `body` lists nicks. The HTTP API lists `nick!user@host` in
-  place of each nick, such as `@op1!op1@host1`.
-- `353.json` says the first parameter marks a channel as public, private or
-  secret. The server always sends `=`, the mark for a public channel.
-- `376.json` gives the text as `End of /MOTD command`. The HTTP API adds a full
-  stop.
-- `401.json` gives the text as `No such nick/channel`. The server sends
-  `No such nick` in answer to a `PRIVMSG` or `NOTICE` to an unknown nick.
-- `433.json` has an example with `*` as `to`. The HTTP API sends `433` only in
-  answer to a `NICK`, with the user's nick as `to`.
-
-The HTTP API also accepts some messages that the files do not allow, such as a
-`JOIN` whose `to` has no `#`.

schema/commands/JOIN.json

@@ -2,15 +2,25 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/JOIN.json",
   "title": "JOIN",
-  "description": "Join a channel. C2S: request to join. S2C: notification that a user joined. RFC 1459 §4.2.1.",
+  "description": "Join a channel. A client sends it to join a channel, which the server creates if it does not exist. The server sends it to every member of the channel when a user joins, the new member included. RFC 1459 §4.2.1.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "JOIN" },
-    "from": { "type": "string", "description": "Nick that joined (S2C)." },
-    "to": { "type": "string", "description": "Channel name.", "pattern": "^#[a-zA-Z0-9_-]+$" }
+    "from": { "type": "string", "description": "The nick that joined. The server sets it." },
+    "to": {
+      "type": "string",
+      "description": "The channel name: # and then 1 to 63 of a-z, A-Z, 0-9, _ and -. The server adds the # if a client leaves it out.",
+      "pattern": "^#?[a-zA-Z0-9_-]{1,63}$"
+    },
+    "body": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "From a client: the channel key as the first string, which a channel with mode +k needs. From the server: the channel name. After a login, and for GET /api/v1/state?initChannelState=1, the server queues a JOIN for each of the session's channels. That JOIN has an empty body."
+    }
   },
   "required": ["command", "to"],
   "examples": [
-    { "command": "JOIN", "from": "alice", "to": "#general" }
+    { "command": "JOIN", "to": "#general" },
+    { "command": "JOIN", "from": "alice", "to": "#general", "body": ["#general"] }
   ]
 }

schema/commands/KICK.json

@@ -2,28 +2,33 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/KICK.json",
   "title": "KICK",
-  "description": "Kick a user from a channel. RFC 1459 §4.2.8.",
+  "description": "Remove a user from a channel. A client sends it, and only a channel operator may. The server sends it to every member of the channel, the removed user included. RFC 1459 §4.2.8.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "KICK" },
-    "from": { "type": "string", "description": "Nick that performed the kick." },
-    "to": { "type": "string", "description": "Channel name.", "pattern": "^#[a-zA-Z0-9_-]+$" },
+    "from": { "type": "string", "description": "The nick that removed the user. The server sets it." },
+    "to": {
+      "type": "string",
+      "description": "The channel name. The server adds the # if a client leaves it out.",
+      "pattern": "^#?[a-zA-Z0-9_-]{1,63}$"
+    },
     "params": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Kicked nick. e.g. [\"alice\"].",
+      "description": "The removed nick. Only the server sends it.",
       "minItems": 1,
       "maxItems": 1
     },
     "body": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Optional kick reason.",
-      "maxItems": 1
+      "description": "From a client: the nick to remove, then an optional reason. From the server: the reason, as one string.",
+      "minItems": 1
     }
   },
-  "required": ["command", "to", "params"],
+  "required": ["command", "to", "body"],
   "examples": [
+    { "command": "KICK", "to": "#general", "body": ["troll", "Behave"] },
     { "command": "KICK", "from": "op1", "to": "#general", "params": ["troll"], "body": ["Behave"] }
   ]
 }

schema/commands/MODE.json

@@ -2,28 +2,29 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/MODE.json",
   "title": "MODE",
-  "description": "Set or query channel/user modes. RFC 1459 §4.2.3.",
+  "description": "Query or change a channel's modes or the user's own modes. A client sends it. The server sends it to every member of the channel when a channel mode changes. A +H or -H sent over the HTTP API is the exception. The server answers it with RPL_CHANNELMODEIS (324) and sends no MODE. RFC 1459 §4.2.3.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "MODE" },
     "from": {
       "type": "string",
-      "description": "Nick that set the mode (S2C only)."
+      "description": "The nick that changed the mode. The server sets it."
     },
     "to": {
       "type": "string",
-      "description": "Channel name.",
-      "pattern": "^#[a-zA-Z0-9_-]+$"
+      "description": "A channel name, which starts with #, or the user's own nick."
     },
-    "params": {
+    "body": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Mode string and optional target nick. e.g. [\"+o\", \"alice\"].",
-      "examples": [["+o", "alice"], ["-m"], ["+v", "bob"]]
+      "description": "From a client: the mode change and then its value, as separate strings, such as \"+o\" and \"bob\". A MODE without a body is a query. From the server: the change and its value, as one string, such as \"+o bob\", or as separate strings, such as \"+k\" and \"secret\".",
+      "examples": [["+o", "bob"], ["-m"], ["+o bob"], ["+k", "secret"]]
     }
   },
-  "required": ["command", "to", "params"],
+  "required": ["command", "to"],
   "examples": [
-    { "command": "MODE", "from": "op1", "to": "#general", "params": ["+o", "alice"] }
+    { "command": "MODE", "to": "#general", "body": ["+o", "bob"] },
+    { "command": "MODE", "from": "op1", "to": "#general", "body": ["+o bob"] },
+    { "command": "MODE", "from": "op1", "to": "#general", "body": ["+k", "secret"] }
   ]
 }

schema/commands/NICK.json

@@ -2,21 +2,21 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/NICK.json",
   "title": "NICK",
-  "description": "Change nickname. C2S: request new nick. S2C: notification of nick change. RFC 1459 §4.1.2.",
+  "description": "Change nick. A client sends it to change its nick. The server sends it to the user's own clients and to the users who share a channel with the user. RFC 1459 §4.1.2.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "NICK" },
-    "from": { "type": "string", "description": "Old nick (S2C)." },
+    "from": { "type": "string", "description": "The old nick. The server sets it." },
     "body": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "New nick (single-element array).",
-      "minItems": 1,
-      "maxItems": 1
+      "description": "The new nick, as the first string. The server sends one string.",
+      "minItems": 1
     }
   },
   "required": ["command", "body"],
   "examples": [
+    { "command": "NICK", "body": ["newnick"] },
     { "command": "NICK", "from": "oldnick", "body": ["newnick"] }
   ]
 }

schema/commands/NOTICE.json

@@ -2,20 +2,21 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/NOTICE.json",
   "title": "NOTICE",
-  "description": "Send a notice. Like PRIVMSG but must not trigger automatic replies. RFC 1459 §4.4.2.",
+  "description": "A notice: a message to a channel or a user that a client must not answer automatically. The server relays it as it relays a PRIVMSG. A NOTICE to a channel with mode +H needs no hashcash stamp. RFC 1459 §4.4.2.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "NOTICE" },
-    "from": { "type": "string" },
-    "to": { "type": "string", "description": "Target: #channel, nick, or * (global)." },
+    "from": { "type": "string", "description": "The sender's nick. The server sets it." },
+    "to": { "type": "string", "description": "A channel name, which starts with #, or a nick." },
     "body": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Notice text lines."
+      "description": "The lines of the notice, one string per line.",
+      "minItems": 1
     }
   },
   "required": ["command", "to", "body"],
   "examples": [
-    { "command": "NOTICE", "from": "server.example.com", "to": "*", "body": ["Server restarting in 5 minutes"] }
+    { "command": "NOTICE", "from": "alice", "to": "#general", "body": ["Back in five minutes"] }
   ]
 }

schema/commands/PART.json

@@ -2,17 +2,20 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/PART.json",
   "title": "PART",
-  "description": "Leave a channel. C2S: request to leave. S2C: notification that a user left. RFC 1459 §4.2.2.",
+  "description": "Leave a channel. A client sends it to leave. The server sends it to every member of the channel when a user leaves, the leaving user included. RFC 1459 §4.2.2.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "PART" },
-    "from": { "type": "string", "description": "Nick that left (S2C)." },
-    "to": { "type": "string", "description": "Channel name.", "pattern": "^#[a-zA-Z0-9_-]+$" },
+    "from": { "type": "string", "description": "The nick that left. The server sets it." },
+    "to": {
+      "type": "string",
+      "description": "The channel name. The server adds the # if a client leaves it out.",
+      "pattern": "^#?[a-zA-Z0-9_-]{1,63}$"
+    },
     "body": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Optional part reason.",
-      "maxItems": 1
+      "description": "The reason for leaving. A client may send one as the first string. The server always sends one string, which is empty when no reason was given."
     }
   },
   "required": ["command", "to"],

schema/commands/PING.json

@@ -2,19 +2,13 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/PING.json",
   "title": "PING",
-  "description": "Keepalive. C2S or S2S. Server responds with PONG. RFC 1459 §4.6.2.",
+  "description": "A check that the server still answers. A client sends it. The server ignores every field but 'command'. Its answer is a PONG in the HTTP response. RFC 1459 §4.6.2.",
   "$ref": "../message.json",
   "properties": {
-    "command": { "const": "PING" },
-    "body": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "Opaque token to be echoed in PONG (single-element array).",
-      "maxItems": 1
-    }
+    "command": { "const": "PING" }
   },
   "required": ["command"],
   "examples": [
-    { "command": "PING", "body": ["1707580000"] }
+    { "command": "PING" }
   ]
 }

schema/commands/PONG.json

@@ -2,20 +2,14 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/PONG.json",
   "title": "PONG",
-  "description": "Keepalive response. S2C or S2S. RFC 1459 §4.6.3.",
+  "description": "The answer to a PING. The server sends it as the HTTP response to the PING, with only 'command' and 'from'. A client's PONG gets ERR_UNKNOWNCOMMAND (421). RFC 1459 §4.6.3.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "PONG" },
-    "from": { "type": "string", "description": "Responding server name." },
-    "body": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "Echoed token from PING (single-element array).",
-      "maxItems": 1
-    }
+    "from": { "type": "string", "description": "The server name." }
   },
-  "required": ["command"],
+  "required": ["command", "from"],
   "examples": [
-    { "command": "PONG", "from": "server.example.com", "body": ["1707580000"] }
+    { "command": "PONG", "from": "neoirc" }
   ]
 }

schema/commands/PRIVMSG.json

@@ -2,16 +2,16 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/PRIVMSG.json",
   "title": "PRIVMSG",
-  "description": "Send a message to a channel or user. C2S: client sends to server. S2C: server relays to recipients. RFC 1459 §4.4.1.",
+  "description": "A message to a channel or a user. A client sends it. The server relays it to every member of the channel, or to the user, and to the sender's own clients. RFC 1459 §4.4.1.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "PRIVMSG" },
-    "from": { "type": "string", "description": "Sender nick (set by server on relay)." },
-    "to": { "type": "string", "description": "Target: #channel or nick.", "examples": ["#general", "alice"] },
+    "from": { "type": "string", "description": "The sender's nick. The server sets it." },
+    "to": { "type": "string", "description": "A channel name, which starts with #, or a nick.", "examples": ["#general", "alice"] },
     "body": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Message lines. One string per line.",
+      "description": "The lines of the message, one string per line.",
       "minItems": 1
     }
   },
@@ -19,6 +19,6 @@
   "examples": [
     { "command": "PRIVMSG", "from": "bob", "to": "#general", "body": ["hello world"] },
     { "command": "PRIVMSG", "from": "bob", "to": "#general", "body": ["line one", "line two"] },
-    { "command": "PRIVMSG", "from": "bob", "to": "alice", "body": ["hey"], "meta": { "sig": "base64...", "alg": "ed25519" } }
+    { "command": "PRIVMSG", "from": "bob", "to": "alice", "body": ["hey"] }
   ]
 }

schema/commands/PUBKEY.json

@@ -1,37 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://sneak.berlin/go/neoirc/schema/commands/PUBKEY.json",
-  "title": "PUBKEY",
-  "description": "Announce or relay a user's public signing key. C2S: client announces key to channel or server. S2C: server relays to channel members. Protocol extension (not in RFC 1459). Body is a structured object (not an array) containing the key material.",
-  "$ref": "../message.json",
-  "properties": {
-    "command": { "const": "PUBKEY" },
-    "from": { "type": "string", "description": "Nick announcing the key (set by server on relay)." },
-    "to": {
-      "type": "string",
-      "description": "Target: #channel to announce to channel members, or omit for server-wide announcement."
-    },
-    "body": {
-      "type": "object",
-      "description": "Key material.",
-      "properties": {
-        "alg": {
-          "type": "string",
-          "description": "Key algorithm.",
-          "enum": ["ed25519"]
-        },
-        "key": {
-          "type": "string",
-          "description": "Base64-encoded public key."
-        }
-      },
-      "required": ["alg", "key"],
-      "additionalProperties": false
-    }
-  },
-  "required": ["command", "body"],
-  "examples": [
-    { "command": "PUBKEY", "from": "alice", "body": { "alg": "ed25519", "key": "base64-encoded-pubkey" } },
-    { "command": "PUBKEY", "from": "alice", "to": "#general", "body": { "alg": "ed25519", "key": "base64-encoded-pubkey" } }
-  ]
-}

schema/commands/QUIT.json

@@ -2,20 +2,20 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/QUIT.json",
   "title": "QUIT",
-  "description": "User disconnected. S2C only. RFC 1459 §4.1.6.",
+  "description": "A user left the server. A client sends it to end its session. The server sends it to the users who shared a channel with the user who left. RFC 1459 §4.1.6.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "QUIT" },
-    "from": { "type": "string", "description": "Nick that quit." },
+    "from": { "type": "string", "description": "The nick that quit. The server sets it." },
     "body": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Optional quit reason.",
-      "maxItems": 1
+      "description": "The reason for leaving. A client may send one as the first string, and the server uses 'Client quit' when it does not. The server always sends one string."
     }
   },
-  "required": ["command", "from"],
+  "required": ["command"],
   "examples": [
-    { "command": "QUIT", "from": "alice", "body": ["Connection reset"] }
+    { "command": "QUIT", "body": ["Gone for the day"] },
+    { "command": "QUIT", "from": "alice", "body": ["Connection closed"] }
   ]
 }

schema/commands/TOPIC.json

@@ -2,20 +2,24 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/commands/TOPIC.json",
   "title": "TOPIC",
-  "description": "Get or set channel topic. C2S: set topic (body present) or query (body absent). S2C: topic change notification. RFC 1459 §4.2.4.",
+  "description": "Set a channel's topic. A client sends it to set the topic. The server sends it to every member of the channel when the topic changes. RFC 1459 §4.2.4.",
   "$ref": "../message.json",
   "properties": {
     "command": { "const": "TOPIC" },
-    "from": { "type": "string", "description": "Nick that changed the topic (S2C)." },
-    "to": { "type": "string", "description": "Channel name.", "pattern": "^#[a-zA-Z0-9_-]+$" },
+    "from": { "type": "string", "description": "The nick that set the topic. The server sets it." },
+    "to": {
+      "type": "string",
+      "description": "The channel name. The server adds the # if a client leaves it out.",
+      "pattern": "^#?[a-zA-Z0-9_-]{1,63}$"
+    },
     "body": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "New topic text (single-element array). Empty array clears the topic.",
-      "maxItems": 1
+      "description": "The new topic. The server joins a client's strings with spaces, and sends the topic as one string. [\"\"] clears the topic.",
+      "minItems": 1
     }
   },
-  "required": ["command", "to"],
+  "required": ["command", "to", "body"],
   "examples": [
     { "command": "TOPIC", "from": "alice", "to": "#general", "body": ["Welcome to the channel"] }
   ]

schema/message.json

@@ -2,67 +2,55 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/message.json",
   "title": "IRC Message Envelope",
-  "description": "Base envelope for all messages. Mirrors IRC wire format (RFC 1459/2812) encoded as JSON over HTTP. The 'command' field carries either an IRC command name (PRIVMSG, JOIN, etc.) or a three-digit numeric reply code (001, 353, 433, etc.).",
+  "description": "Every message in the HTTP API is one JSON object with these fields. Only 'command' is always present.",
   "type": "object",
   "properties": {
     "id": {
       "type": "string",
       "format": "uuid",
-      "description": "Server-assigned message UUID. Present on all server-originated messages."
+      "description": "The message's UUID, which the server assigns. Present on every message the server queues for a client."
     },
     "command": {
       "type": "string",
-      "description": "IRC command name (PRIVMSG, JOIN, NICK, etc.) or three-digit numeric reply code (001, 353, 433, etc.).",
-      "examples": ["PRIVMSG", "JOIN", "001", "353", "433"]
+      "description": "An IRC command name, such as PRIVMSG, or the name of a numeric reply, such as RPL_WELCOME. The server reads a client's command in any case and sends it in upper case.",
+      "examples": ["PRIVMSG", "JOIN", "RPL_WELCOME", "ERR_NICKNAMEINUSE"]
+    },
+    "code": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 999,
+      "description": "The number of a numeric reply, such as 1 for RPL_WELCOME. Absent on other messages."
     },
     "from": {
       "type": "string",
-      "description": "Source — nick for user messages, server name for server messages. Equivalent to IRC prefix."
+      "description": "The sender's nick, or the server name on a numeric reply or a PONG. The server sets it and ignores it from a client."
     },
     "to": {
       "type": "string",
-      "description": "Target — channel (#name) or nick. Equivalent to first IRC parameter for most commands."
+      "description": "The target: a channel name, such as #general, or a nick. A WALLOPS has * here."
     },
     "params": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Additional parameters (used primarily by numeric replies). Equivalent to IRC middle parameters."
+      "description": "The message's other parameters, in order. KICK events and many numeric replies have it. The server ignores it from a client."
     },
     "body": {
-      "oneOf": [
-        {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "Array of strings (one per line for text messages)."
-        },
-        {
-          "type": "object",
-          "description": "Structured data (e.g. PUBKEY key material).",
-          "additionalProperties": true
-        }
-      ],
-      "description": "Message body. MUST be an array or object, never a raw string. Arrays represent lines of text; objects carry structured data. This enables deterministic canonicalization (RFC 8785 JCS) for signing."
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "An array of strings, never a bare string. In a PRIVMSG or NOTICE, each string is one line of text."
     },
     "ts": {
       "type": "string",
       "format": "date-time",
-      "description": "Server-assigned timestamp (ISO 8601). Not present in original IRC; added for HTTP transport."
+      "description": "The time the server stored the message, as an RFC 3339 time in UTC."
     },
     "meta": {
       "type": "object",
-      "description": "Extensible metadata. Used for signatures (meta.sig, meta.alg), hashes (meta.hash), and client extensions.",
+      "description": "An object of extra data. Every message the server queues for a client has meta, which is {} when there is none. The server keeps a client's meta only on a PRIVMSG or NOTICE, and relays it unchanged.",
       "properties": {
-        "sig": {
+        "hashcash": {
           "type": "string",
-          "description": "Base64-encoded cryptographic signature over the canonical message form."
-        },
-        "alg": {
-          "type": "string",
-          "description": "Signature algorithm (e.g. 'ed25519')."
-        },
-        "hash": {
-          "type": "string",
-          "description": "Hash of the canonical message form (e.g. 'sha256:base64...')."
+          "description": "A hashcash stamp. A PRIVMSG to a channel with mode +H needs one."
         }
       },
       "additionalProperties": true

schema/numerics/001.json

@@ -2,32 +2,45 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/001.json",
   "title": "001 RPL_WELCOME",
-  "description": "Welcome message sent after successful session creation. RFC 2812 \u00a75.1.",
+  "description": "Welcomes the user. Sent after a session is created, after a login, and in answer to MOTD. RFC 2812 §5.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "001"
+      "const": "RPL_WELCOME"
+    },
+    "code": {
+      "const": 1
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
       "type": "string",
-      "description": "Target nick."
+      "description": "The user's nick."
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Welcome text lines."
+      "description": "One string: 'Welcome to the network, ' and the user's nick.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
     "body"
   ],
   "examples": [
     {
-      "command": "001",
+      "command": "RPL_WELCOME",
+      "code": 1,
+      "from": "neoirc",
       "to": "alice",
       "body": [
         "Welcome to the network, alice"

schema/numerics/002.json

@@ -2,34 +2,48 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/002.json",
   "title": "002 RPL_YOURHOST",
-  "description": "Server host info sent after session creation. RFC 2812 \u00a75.1.",
+  "description": "The server's name and version. Sent right after RPL_WELCOME. RFC 2812 §5.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "002"
+      "const": "RPL_YOURHOST"
+    },
+    "code": {
+      "const": 2
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Host info lines."
+      "description": "One string: 'Your host is ', the server name, ', running version ' and the version.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
     "body"
   ],
   "examples": [
     {
-      "command": "002",
+      "command": "RPL_YOURHOST",
+      "code": 2,
+      "from": "neoirc",
       "to": "alice",
       "body": [
-        "Your host is neoirc.example.com, running version 0.1.0"
+        "Your host is neoirc, running version dev"
       ]
     }
   ]

schema/numerics/003.json

@@ -2,31 +2,45 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/003.json",
   "title": "003 RPL_CREATED",
-  "description": "Server creation date. RFC 2812 \u00a75.1.",
+  "description": "The date the server last started. Sent right after RPL_YOURHOST. RFC 2812 §5.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "003"
+      "const": "RPL_CREATED"
+    },
+    "code": {
+      "const": 3
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Text lines."
+      "description": "One string: 'This server was created ' and the start date as YYYY-MM-DD.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
     "body"
   ],
   "examples": [
     {
-      "command": "003",
+      "command": "RPL_CREATED",
+      "code": 3,
+      "from": "neoirc",
       "to": "alice",
       "body": [
         "This server was created 2026-02-01"

schema/numerics/004.json

@@ -2,37 +2,64 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/004.json",
   "title": "004 RPL_MYINFO",
-  "description": "Server info (name, version, available modes). RFC 2812 \u00a75.1.",
+  "description": "The server's name, its version, and its lists of user and channel modes. Sent right after RPL_CREATED. RFC 2812 §5.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "004"
+      "const": "RPL_MYINFO"
+    },
+    "code": {
+      "const": 4
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[server_name, version, user_modes, channel_modes]."
+      "description": "The server name, the version, the user modes 'ow' and the channel modes 'Hbiklmnostv'.",
+      "minItems": 4,
+      "maxItems": 4
+    },
+    "body": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "One empty string.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
-    "params"
+    "params",
+    "body"
   ],
   "examples": [
     {
-      "command": "004",
+      "command": "RPL_MYINFO",
+      "code": 4,
+      "from": "neoirc",
       "to": "alice",
       "params": [
-        "neoirc.example.com",
-        "0.1.0",
-        "o",
-        "imnst+ov"
+        "neoirc",
+        "dev",
+        "ow",
+        "Hbiklmnostv"
+      ],
+      "body": [
+        ""
       ]
     }
   ]

schema/numerics/322.json

@@ -2,38 +2,55 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/322.json",
   "title": "322 RPL_LIST",
-  "description": "Channel list entry. One per channel in response to LIST. RFC 1459 \u00a76.2.",
+  "description": "One channel in the answer to LIST. The answer has one per channel, except a secret channel, one with mode +s, that the user is not on. RFC 1459 §6.2.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "322"
+      "const": "RPL_LIST"
+    },
+    "code": {
+      "const": 322
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[channel, visible_count]."
+      "description": "The channel name and its number of members.",
+      "minItems": 2,
+      "maxItems": 2
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Channel topic."
+      "description": "One string: the channel's topic, empty when it has none.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
-    "params"
+    "params",
+    "body"
   ],
   "examples": [
     {
-      "command": "322",
+      "command": "RPL_LIST",
+      "code": 322,
+      "from": "neoirc",
       "to": "alice",
       "params": [
         "#general",

schema/numerics/323.json

@@ -2,26 +2,49 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/323.json",
   "title": "323 RPL_LISTEND",
-  "description": "End of channel list. RFC 1459 \u00a76.2.",
+  "description": "The end of the answer to LIST. RFC 1459 §6.2.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "323"
+      "const": "RPL_LISTEND"
+    },
+    "code": {
+      "const": 323
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "End of /LIST",
+      "description": "One string: 'End of /LIST'.",
+      "minItems": 1,
       "maxItems": 1
     }
   },
   "required": [
     "command",
-    "to"
+    "code",
+    "from",
+    "to",
+    "body"
+  ],
+  "examples": [
+    {
+      "command": "RPL_LISTEND",
+      "code": 323,
+      "from": "neoirc",
+      "to": "alice",
+      "body": [
+        "End of /LIST"
+      ]
+    }
   ]
 }

schema/numerics/332.json

@@ -2,39 +2,55 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/332.json",
   "title": "332 RPL_TOPIC",
-  "description": "Channel topic (sent on JOIN or TOPIC query). RFC 1459 \u00a76.2.",
+  "description": "A channel's topic. Sent to a client after it sets the topic, and after it joins a channel that has one. Also sent for each of a session's channels that has one after a login, and for GET /api/v1/state?initChannelState=1. RFC 1459 §6.2.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "332"
+      "const": "RPL_TOPIC"
+    },
+    "code": {
+      "const": 332
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[channel]."
+      "description": "The channel name.",
+      "minItems": 1,
+      "maxItems": 1
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Topic text."
+      "description": "One string: the topic.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
     "params",
     "body"
   ],
   "examples": [
     {
-      "command": "332",
+      "command": "RPL_TOPIC",
+      "code": 332,
+      "from": "neoirc",
       "to": "alice",
       "params": [
         "#general"

schema/numerics/353.json

@@ -2,46 +2,62 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/353.json",
   "title": "353 RPL_NAMREPLY",
-  "description": "Channel member list. Sent on JOIN or NAMES query. RFC 1459 \u00a76.2.",
+  "description": "A channel's members. Sent to a client after it joins a channel, and in answer to NAMES. Also sent for each of a session's channels after a login, and for GET /api/v1/state?initChannelState=1. RFC 1459 §6.2.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "353"
+      "const": "RPL_NAMREPLY"
+    },
+    "code": {
+      "const": 353
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[channel_type, channel]. channel_type: = (public), * (private), @ (secret)."
+      "description": "'=' and the channel name. The server always sends '='.",
+      "minItems": 2,
+      "maxItems": 2
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Space-separated list of nicks. Prefixed with @ for ops, + for voiced."
+      "description": "One string: the members as nick!user@host, separated by spaces. '@' comes before a channel operator and '+' before a voiced member. The host is '*' when the server does not know it.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
     "params",
     "body"
   ],
   "examples": [
     {
-      "command": "353",
+      "command": "RPL_NAMREPLY",
+      "code": 353,
+      "from": "neoirc",
       "to": "alice",
       "params": [
         "=",
         "#general"
       ],
       "body": [
-        "@op1 alice bob +voiced1"
+        "@op1!op1@host1 alice!alice@host2 +bob!bob@host3"
       ]
     }
   ]

schema/numerics/366.json

@@ -2,34 +2,62 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/366.json",
   "title": "366 RPL_ENDOFNAMES",
-  "description": "End of NAMES list. RFC 1459 \u00a76.2.",
+  "description": "The end of a channel's member list. It comes after the RPL_NAMREPLY for the channel. RFC 1459 §6.2.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "366"
+      "const": "RPL_ENDOFNAMES"
+    },
+    "code": {
+      "const": 366
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[channel]."
+      "description": "The channel name.",
+      "minItems": 1,
+      "maxItems": 1
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "End of /NAMES list",
+      "description": "One string: 'End of /NAMES list'.",
+      "minItems": 1,
       "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
-    "params"
+    "params",
+    "body"
+  ],
+  "examples": [
+    {
+      "command": "RPL_ENDOFNAMES",
+      "code": 366,
+      "from": "neoirc",
+      "to": "alice",
+      "params": [
+        "#general"
+      ],
+      "body": [
+        "End of /NAMES list"
+      ]
+    }
   ]
 }

schema/numerics/372.json

@@ -2,31 +2,45 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/372.json",
   "title": "372 RPL_MOTD",
-  "description": "MOTD line. One message per line of the MOTD. RFC 2812 \u00a75.1.",
+  "description": "One line of the message of the day. The server sends one per line, after RPL_MOTDSTART. RFC 2812 §5.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "372"
+      "const": "RPL_MOTD"
+    },
+    "code": {
+      "const": 372
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "MOTD line text (prefixed with '- ')."
+      "description": "One string: '- ' and the line.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
     "body"
   ],
   "examples": [
     {
-      "command": "372",
+      "command": "RPL_MOTD",
+      "code": 372,
+      "from": "neoirc",
       "to": "alice",
       "body": [
         "- Welcome to our server!"

schema/numerics/375.json

@@ -2,25 +2,49 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/375.json",
   "title": "375 RPL_MOTDSTART",
-  "description": "Start of MOTD. RFC 2812 \u00a75.1.",
+  "description": "The start of the message of the day. Sent after RPL_LUSERME (255) when the server has a message of the day. RFC 2812 §5.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "375"
+      "const": "RPL_MOTDSTART"
+    },
+    "code": {
+      "const": 375
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Text lines."
+      "description": "One string: '- ', the server name and ' Message of the Day -'.",
+      "minItems": 1,
+      "maxItems": 1
     }
   },
   "required": [
     "command",
-    "to"
+    "code",
+    "from",
+    "to",
+    "body"
+  ],
+  "examples": [
+    {
+      "command": "RPL_MOTDSTART",
+      "code": 375,
+      "from": "neoirc",
+      "to": "alice",
+      "body": [
+        "- neoirc Message of the Day -"
+      ]
+    }
   ]
 }

schema/numerics/376.json

@@ -2,26 +2,49 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/376.json",
   "title": "376 RPL_ENDOFMOTD",
-  "description": "End of MOTD. RFC 2812 \u00a75.1.",
+  "description": "The end of the message of the day. RFC 2812 §5.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "376"
+      "const": "RPL_ENDOFMOTD"
+    },
+    "code": {
+      "const": 376
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "End of /MOTD command",
+      "description": "One string: 'End of /MOTD command.'.",
+      "minItems": 1,
       "maxItems": 1
     }
   },
   "required": [
     "command",
-    "to"
+    "code",
+    "from",
+    "to",
+    "body"
+  ],
+  "examples": [
+    {
+      "command": "RPL_ENDOFMOTD",
+      "code": 376,
+      "from": "neoirc",
+      "to": "alice",
+      "body": [
+        "End of /MOTD command."
+      ]
+    }
   ]
 }

schema/numerics/401.json

@@ -2,45 +2,61 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/401.json",
   "title": "401 ERR_NOSUCHNICK",
-  "description": "No such nick/channel. RFC 1459 \u00a76.1.",
+  "description": "No user has that nick. RFC 1459 §6.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "401"
+      "const": "ERR_NOSUCHNICK"
+    },
+    "code": {
+      "const": 401
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[target_nick]."
+      "description": "The nick that was not found.",
+      "minItems": 1,
+      "maxItems": 1
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "No such nick/channel",
+      "description": "One string: 'No such nick' in answer to a PRIVMSG or NOTICE, and 'No such nick/channel' in answer to anything else.",
+      "minItems": 1,
       "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
-    "params"
+    "params",
+    "body"
   ],
   "examples": [
     {
-      "command": "401",
+      "command": "ERR_NOSUCHNICK",
+      "code": 401,
+      "from": "neoirc",
       "to": "alice",
       "params": [
         "bob"
       ],
       "body": [
-        "No such nick/channel"
+        "No such nick"
       ]
     }
   ]

schema/numerics/403.json

@@ -2,39 +2,55 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/403.json",
   "title": "403 ERR_NOSUCHCHANNEL",
-  "description": "No such channel. RFC 1459 \u00a76.1.",
+  "description": "No channel has that name. A JOIN with a channel name that the server does not allow gets it too. RFC 1459 §6.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "403"
+      "const": "ERR_NOSUCHCHANNEL"
+    },
+    "code": {
+      "const": 403
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[channel_name]."
+      "description": "The channel name.",
+      "minItems": 1,
+      "maxItems": 1
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "No such channel",
+      "description": "One string: 'No such channel'.",
+      "minItems": 1,
       "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
-    "params"
+    "params",
+    "body"
   ],
   "examples": [
     {
-      "command": "403",
+      "command": "ERR_NOSUCHCHANNEL",
+      "code": 403,
+      "from": "neoirc",
       "to": "alice",
       "params": [
         "#nonexistent"

schema/numerics/433.json

@@ -2,42 +2,58 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/433.json",
   "title": "433 ERR_NICKNAMEINUSE",
-  "description": "Nickname is already in use. RFC 1459 \u00a76.1.",
+  "description": "Another user has the nick. Sent in answer to a NICK. RFC 1459 §6.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "433"
+      "const": "ERR_NICKNAMEINUSE"
+    },
+    "code": {
+      "const": 433
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick, which has not changed."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[requested_nick]."
+      "description": "The nick that was asked for.",
+      "minItems": 1,
+      "maxItems": 1
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Nickname is already in use",
+      "description": "One string: 'Nickname is already in use'.",
+      "minItems": 1,
       "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
-    "params"
+    "params",
+    "body"
   ],
   "examples": [
     {
-      "command": "433",
-      "to": "*",
+      "command": "ERR_NICKNAMEINUSE",
+      "code": 433,
+      "from": "neoirc",
+      "to": "alice",
       "params": [
-        "alice"
+        "bob"
       ],
       "body": [
         "Nickname is already in use"

schema/numerics/442.json

@@ -2,34 +2,62 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/442.json",
   "title": "442 ERR_NOTONCHANNEL",
-  "description": "You're not on that channel. RFC 1459 \u00a76.1.",
+  "description": "The user is not on that channel. RFC 1459 §6.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "442"
+      "const": "ERR_NOTONCHANNEL"
+    },
+    "code": {
+      "const": 442
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[channel]."
+      "description": "The channel name.",
+      "minItems": 1,
+      "maxItems": 1
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "You're not on that channel",
+      "description": "One string: 'You're not on that channel'.",
+      "minItems": 1,
       "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
-    "params"
+    "params",
+    "body"
+  ],
+  "examples": [
+    {
+      "command": "ERR_NOTONCHANNEL",
+      "code": 442,
+      "from": "neoirc",
+      "to": "alice",
+      "params": [
+        "#general"
+      ],
+      "body": [
+        "You're not on that channel"
+      ]
+    }
   ]
 }

schema/numerics/482.json

@@ -2,34 +2,62 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sneak.berlin/go/neoirc/schema/numerics/482.json",
   "title": "482 ERR_CHANOPRIVSNEEDED",
-  "description": "You're not channel operator. RFC 1459 \u00a76.1.",
+  "description": "The user is not a channel operator, and the command needs one. RFC 1459 §6.1.",
   "$ref": "../message.json",
   "properties": {
     "command": {
-      "const": "482"
+      "const": "ERR_CHANOPRIVSNEEDED"
+    },
+    "code": {
+      "const": 482
+    },
+    "from": {
+      "type": "string",
+      "description": "The server name."
     },
     "to": {
-      "type": "string"
+      "type": "string",
+      "description": "The user's nick."
     },
     "params": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "[channel]."
+      "description": "The channel name.",
+      "minItems": 1,
+      "maxItems": 1
     },
     "body": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "You're not channel operator",
+      "description": "One string: 'You're not channel operator'.",
+      "minItems": 1,
       "maxItems": 1
     }
   },
   "required": [
     "command",
+    "code",
+    "from",
     "to",
-    "params"
+    "params",
+    "body"
+  ],
+  "examples": [
+    {
+      "command": "ERR_CHANOPRIVSNEEDED",
+      "code": 482,
+      "from": "neoirc",
+      "to": "alice",
+      "params": [
+        "#general"
+      ],
+      "body": [
+        "You're not channel operator"
+      ]
+    }
   ]
 }