neoirc/schema/README.md

# Message schemas

This directory holds JSON Schema files (draft 2020-12) for the messages that the
neoirc HTTP API carries. `message.json` describes the envelope every message
uses. `commands/` has files for some of the IRC commands. `numerics/` has files
for some of the numeric replies. `README.md` at the repository root documents
the protocol.

## The envelope

Every message is one JSON object. These are the fields it can have:

- `command`: the IRC command name, such as `PRIVMSG`, or the name of a numeric
  reply, such as `RPL_WELCOME`. Always present.
- `code`: the number of a numeric reply, such as `1` for `RPL_WELCOME`. Absent
  on other messages.
- `id`: the message's UUID, assigned by the server.
- `from`: the sender's nick, or the server name on a server message.
- `to`: the target, such as a channel name starting with `#` or a nick.
- `params`: other parameters, in order, as an array of strings. `KICK` events
  and many numeric replies have it. The server ignores `params` sent by a
  client.
- `body`: an array of strings. It is never a bare string. In a `PRIVMSG` or
  `NOTICE`, each string is one line of text.
- `ts`: when the server stored the message, as an RFC 3339 time in UTC, such as
  `2026-10-27T12:00:00.123Z`.
- `meta`: an object of extra data, such as a hashcash stamp in `meta.hashcash`.
  A hashcash stamp is a short string that takes a computer some work to make. A
  channel with mode `+H` needs one in every `PRIVMSG`. The server relays the
  `meta` of a `PRIVMSG` or `NOTICE` unchanged. It drops the `meta` of every
  other command.

A `PRIVMSG` as the IRC listener sends it, and as the HTTP API sends it without
`id`, `ts` and `meta`:

```
IRC:  :alice!alice@* PRIVMSG #general :hello world
JSON: {"command": "PRIVMSG", "from": "alice", "to": "#general", "body": ["hello world"]}
```

A numeric reply has its name in `command` and its number in `code`. This `353`
reply lists the members of `#general`, again without `id`, `ts` and `meta`:

```
{"command": "RPL_NAMREPLY", "code": 353, "from": "neoirc", "to": "alice",
 "params": ["=", "#general"], "body": ["@op1!op1@host1 alice!alice@host2"]}
```

A `body` with two strings is a two-line message:

```
{"command": "PRIVMSG", "to": "#general", "body": ["line one", "line two"]}
```

## Files

Commands, in `commands/`:

- `PRIVMSG.json`: a message to a channel or a user.
- `NOTICE.json`: a notice. A client must not answer a notice 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.
- `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).

Numeric replies, in `numerics/`:

- `001.json`: `RPL_WELCOME`, which welcomes a new user.
- `002.json`: `RPL_YOURHOST`, the server's name and version.
- `003.json`: `RPL_CREATED`, the date the server started.
- `004.json`: `RPL_MYINFO`, the server's 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.
- `353.json`: `RPL_NAMREPLY`, a channel's members.
- `366.json`: `RPL_ENDOFNAMES`, the end of the member list.
- `372.json`: `RPL_MOTD`, one line of the message of the day.
- `375.json`: `RPL_MOTDSTART`, the start of the message of the day.
- `376.json`: `RPL_ENDOFMOTD`, the end of the message of the day.
- `401.json`: `ERR_NOSUCHNICK`, the nick does not exist.
- `403.json`: `ERR_NOSUCHCHANNEL`, the channel does not exist.
- `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 server

Where a schema file and the server disagree, the server is right:

- `message.json` and the numeric files put the three-digit code in `command` and
  have no `code` field. The server puts the reply's name in `command` and its
  number in `code`.
- `message.json` allows an object as `body`. The server reads only arrays of
  strings. A `PRIVMSG` with an object 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 server keeps `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 server 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 server's `JOIN` event repeats the channel name
  there.
- `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 server reads a client's
  `KICK` from `body`: the nick, then an optional reason.
- `MODE.json` puts the mode change in `params`. The server uses `body` instead.
  A client sends the change and any value as separate strings, such as `"+o"`
  and `"bob"`. The server's `MODE` event has one string such as `"+o bob"`, or
  the change and its value as two strings, such as `"+k"` and `"secret"`.
- `NOTICE.json` allows `*` as `to`. The server answers that 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
  server ignores the `body` of a `PING`. It answers the HTTP request itself with
  `{"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 only the server sends `QUIT`. A client can send it too, to
  end its session. The client's `QUIT` can carry a reason in `body`.
- `TOPIC.json` says a `TOPIC` without a `body` queries the topic. Over the HTTP
  API a `TOPIC` without a `body` gets `ERR_NEEDMOREPARAMS` (461).
- `TOPIC.json` says an empty array clears the topic. The server answers `[]`
  with `ERR_NEEDMOREPARAMS` (461). A `body` of `[""]` clears the topic.
- `003.json` describes the server's creation date. The server sends the date it
  last started.
- `004.json` has example mode lists. The server sends an empty string as the
  user modes and `ikmnostl` as the channel modes.
- `322.json` says `LIST` gets one reply per channel. The server leaves out each
  secret channel that the user is not on.
- `353.json` says `body` lists nicks. Over the HTTP API the server 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 server adds a full
  stop.
- `401.json` gives the text as `No such nick/channel`. For a `PRIVMSG` or
  `NOTICE` to an unknown nick, the server sends `No such nick`.
- `433.json` has an example with `*` as `to`. Over the HTTP API the server sends
  `433` only in answer to a `NICK`, with the user's nick as `to`.

The server also accepts some messages that the files do not allow, such as a
channel name without its `#`.