Make the schema files match the server (closes #218)

Each file in schema/ now describes what the HTTP API on next sends and
accepts. A numeric reply has its name in command and its number in code.
body is always an array of strings. MODE, KICK and JOIN carry their
values in body, and TOPIC needs a non-empty body. PING takes no token,
and its PONG is the HTTP response. A channel name is limited to 63
characters, and the leading # is optional from a client.

PUBKEY.json is deleted, since the server has no such command. The
section of schema/README.md that listed the differences is removed,
and the sentences it made false are corrected.

Model: opus-5-5

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"
+      ]
+    }
   ]
 }