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

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`: 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`, which is the HTTP response to it.

Numeric replies, in `numerics/`:

- `001.json`: `RPL_WELCOME`, which welcomes the user.
- `002.json`: `RPL_YOURHOST`, the server's name and version.
- `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.
- `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.