# Message schemas

This directory holds JSON Schema files (draft 2020-12) for the messages that the
neoirc HTTP API carries. `message.json` describes the fields that every message
can have. `commands/` has files for some commands. `numerics/` has files for
some of the numeric replies. A numeric reply is a server reply named by a
three-digit number, such as `001`. `README.md` at the repository root documents
the protocol.

The server can also run an IRC listener for ordinary IRC clients. The IRC
listener sends plain IRC lines, which these files do not describe.

## Message fields

Every message is one JSON object, which `message.json` calls the envelope. 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, a unique ID that the server assigns.
- `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`: 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`
  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`: the time the server stored the message. It is 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
  `PRIVMSG` to a channel with mode `+H` needs one. The HTTP API relays the
  `meta` of a `PRIVMSG` or `NOTICE` unchanged. It drops the `meta` of every
  other command.

Here is one `PRIVMSG` as the IRC listener sends it and as the HTTP API sends it.
The JSON leaves out `id`, `ts` and `meta`:

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

In the JSON, a numeric reply has its name in `command` and its number in `code`.
This `353` reply lists the members of `#general`. The JSON again leaves out
`id`, `ts` and `meta`:

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

A `PRIVMSG` whose `body` has 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, 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.
- `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`, which says when the server was created.
- `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 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 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 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 `#`.